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SECTION 1 

INTRODUCTION TO FORMS 


INTRODUCTION 

The Prime Forms Management System (FORMS) provides a convenient and 
natural method ot defining a form with a language designed for such a 
purpose. Defined forms may then be read pr written by any application 
program that is capable of using Prime's Input-Output Control Syston 
(IOCS). Application programs communicate with FORMS through 
input/output statanents native to the host language. (The host 
language is the language in v^hich the application program source was 
written.) Programs that currently run in an interactive mode may 
easily be converted to use FORMS. 

SCOPE OF DOCUMENT 

This document is divided into four parts. 

The first part. Sections 1 through 3, contains TUTORIAL INFORMATION. 
These sections are intended to give the user a brief introduction to 
forms and quickly show the user how to use FORMS. 

The second portion of this document. Sections 4 through 6, contains 
REFERENCE INFORMATION. Some of the material discussed in Sections 1 - 
3 is repeated, but these sections give more detail on each topic 
relating to FORMS. Section 4 is a detailed discussion of the FORMS 
run-time directives used in the coding of application programs. 
Section 5 describes in detail how to create a form descriptor, which 
describes to FOF^S the complete format of a form both on the terminal 
display screen and in the conputer system data record. Section 6 tells 
in more detail the features for storing and maintaining form 
descriptors in the FORMS catalog. 

The third portion of this docunent. Sections 7 and 8, are of particular 
interest to the programmer. Section 7 describes an application program 
written in FORTRAN, and Section 8 discusses an example program written 
in COBOL. 

The last part of the document is the appendices. The appendices 
contain information that are needed less frequently by the FORMS user, 
for instance "Installation". Appendices also contain information to 
support material presented in earlier sections, such as program 
listings and form descriptor listings. Advanced FORMS usage and error 
messages are the final appendices. 
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PURPOSE OF FOIMS 

FORMS simplifies and standardizes the transfer of data fields (or 
groups of data fields) between application programs and page-oriented 
video terminals and hard-copy devices. FORi'IS provides easy-to-use 
facilities tor defining how data fields are to be displayed at or 
received from one or more block-mode terminal types, and FORMS uses the 
data definitions at run-time to automatically control the data 
transfer. 

In addition, FCRMS provides centralized administrative control and 
simplified maintenance. Through commands to the FORMS Adninistrative 
Processor, a user can add, delete, or change either the forms 
themselves, or the terminal type. 

Finally, FCRMS provides the user with a set of run-time directives that 
reside in a special subroutine library. 

ADVANTAGES OF USING FORMS 

Because the user-terminal screen can be formatted to resemble a source 
document (i.e., the form on paper), FORMS is easy to use, and allows 
user personnel to be trained quickly. Also, any input data errors may 
be corrected before they are read by the application program since 
visual verification of the data at the terminal, the ability to retype 
data fields, and the ability to hignlight errors are all possible. 

Some additional advantages are: 


1. The user is more ccxnfortable using a form displayed at the 
terminal that looks the same as the printed form. 

2. The user can enter information in any order, by movirg the 
terminal cursor to the correct data itan location. 

3. The user can see the information and can see v^iat information, if 
any, is missing. 

4. It is possible for the user to make corrections to entries in the 
form before transmitting them from the user terminal to the 
computer. 

5. Computer processing time is minimized while updating or entering 
a form since FORMS "oft loads" the CPU, i.e., it is not 
interacting with the user on a character by character basis. 
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FORMS INTERFACES TO miMOS 

Prime's Forms Management Systan consists of three major components: 
the FORMS Description Language (FDL), the FORMS Adninistrative 
Processor (FAP), and the FORMS Run-Time library. These components wark 
together to create, administrate, and run forms-oriented applications. 
Figure 1-1 shov,?s a functional overview of FORMS and its relation to 
scxne FRIMOS systan components. FORMS can be applied quickly in simple 
logical steps since each component is independent. 

Figure 1-1 illustrates the various steps that go into the creation and 
use of a FORMS program. 

Part A of the figure shows the development of the applications program. 
First, the source code in created, using Prime's text editor (ED). The 
source code is then translated by the appropriate compiler or assembler 
(FTN, COBOL, RPG, PIMA). The object code is then loaded using SEG or 
LOAD, and the applications program is ready to run. (See the 
appropriate language user's guide tor details). 

The program thus created contains FORMS directives (for example, in 
FORTRAN, the directives are in FORMAT statements). Section 2 of this 
guide explains how to write applications programs that include FORMS 
directives. Section 7 illustrates this process with a sample FORTRAN 
program; section 8 illustrates it with a sample COBOL progran. 

Part B of Figure 1-1 shows the dual nature of I/O in the executing 
program. Standard I/O statements interface with the terminal through 
Prime's Input/Output Control System (IOCS, see PRIMOS Subroutines 
Reference Guide) . FORt-IS I/O directives interface through the FORMS 
run-time package. 

Part C of Figure 1-1 shows how the run-time package receives 
information. Notice how closely the user's work here parallels the 
user's creation of the applications program. 

• The editor is used to create the form definition source: i.e., 

the STREAM and FORMAT descriptors. Section 3 of this guide 

explains how to create these descriptors. 

• The FDL translator is invoked to translate the source code into 
binary. Use of FDL is explained in Section 5. 

• The Forms Administrative Processor (FAP) loads the object code 

into the FORMS directory, where it is available for run-time 

use. Section 6 of this guide explains how to use FAP. 
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Programming Larquage Interface 

Ihe application program source may be written in COBOL, FORTRAN, 
RPG-II, PMA, or any language capable of interaction with Prime's 
Input-Output Control Systan (IOCS). For further information about 
IOCS, refer to the Reference Guide, FRIMOS Subroutines. For 
information on programming in the languages mentioned, refer to the 
appropriate larquage reference guide, i^pplication programs communicate 
with FORMS by means of input/output statements specified within the 
format of the source iarguage (e.g., FORTRAN formatted READ and WRITE 
statements) . 

Terminal Software Interface 


F0R4S provides a means for displaying information on the screen. The 
FORMS display on the screen shows v^^iat fields are available for the 
user to type-in data to be transmitted to the application program. The 
screen handling allows the user to validate data because nothing is 
transmitted to the application program until the transmit key is 
pressed at the terminal. Thus, the user can enter data, visually 
verify it, move the terminal cursor to any incorrect entry and enter 
the correct data, and transmit each line of data. 

Opjerating System Interface 

FORMS operates under the control of PRIMOS, the Prime operating system. 

Additionally, because the fOFMS interface to application programs is 
through standard read/write statements, existing batch-oriented 
programs can be readily adapted to run using local and remote'terminals 
without major re-programming. 

FORMS keeps application programs, the forms they use, and terminals 
they use separated until run-time so that changes can be made in one 
area without necessarily affecting the other two. With this 
flexibility, terminal typas may be changed; the vay a form is 
organized at a particular terminal may be changed; or old forms may be 
described for new terminals. These changes, and many more, are all 
possible without affecting operational programs. 
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FORMS ADMINISTRATIVE PROCESSOR 
Purpose 


The Forms Administrative Processor (FAP) allows the user to maintain 
the fORMS catalog. This catalog contains the object files created by 
FDD. FAP also allows control of the terminal types and lines that are 
associated with a form. 

FORMS Definition Catalog 


The FORMS definition catalog is a segment directory that contains the 
binary representations, generated by FDL, of all the STREAM and FORMAT 
descriptors (see Section 3) available within the system configuration. 
After a form definition is translated by FDL, it is entered in the 
FCRMS definition catalog with the FAP (Forms Administrative Processor) 
coitmand. Refer to Section 6 for details of the FAP ccmmand. The FORMS 
catalog is in the FORMS system UFD, FORMS*. 

FAP Functions 


FAP performs the following: 


• CREATE the FORMS catalog UFD and the segment directory 

associated with the specified form. 

• ADD binary files translated by FDL to the FORMS directory. 

• REPLACE binary files in the t'ORMS directory. 

• PURGE (delete) binary files from the FORMS directory. 

• LIST the binary files in the FORMS directory. 

• Add, replace and remove user terminal types on the Terminal 

Configuration Block. 

• GENERATE $INSERT files for the run-time device subroutine. 
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RELATED DOCUMENTS 


Tile following Prime documents contain additional supporting information 
for the FORMS user. 


Language Manuals 
Docunent No. Title 


Pm3031 

PDR3056 

FER3057 

FDR3104 


RPG II Progranmers Guide 

COBOL Programmers Guide 

FORTRAN Prograirmers Guide 

New User's Guide to Editor and Runoff 


Operating System and Utilities 
Document No. Title 


PER3061 

FDR3108 

PER3621 


Fteference Guide, MIDAS 
Reference Guide, FRIMOS Commands 
Reference Guide, Subroutines 
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SECTION 2 

WRITING APPLICATION mOGRAMS FOR USE WITH FORMS 


INTRODUCTION 

This section gives an overview of how to write application programs for 
use with FORMS. A more detailed discussion of this task is provided in 
the programming examples in Sections 7 and 3. 

Figure 2-1 shows the flow of instructions and data in an application 
using FORMS. The user must control that flow of data by special I/O 
statonents that use FORMS run-time directives. 

This section discusses how to write I/O statements using the FORMS 
run-time directives. I/O statements are the only interface to FORMS in 
the application program. Sections 3 and 6 describe how to write a form 
descriptor and install it in the FORMS catalog (a UFD named FORMS*). 


PRINCIPLES OF OPERATION 

Programs that are written in standard languages such as FCRTRAN or 
COBOL can interact with formatted (sometimes called "block mode") 
terminals in either one of two ways. One solution is the user can 
supply, in the application program, all of the control character 
sequences to the terminal that are needed to output each field (data 
area). This usually requires several bytes of cursor positioning 
information, plus field identifier and attribute bytes, plus the field 
data, and the field terminator byte. The application program can 
interpret the character input stream from the terminal, distinguish 
input data frcm control data, and process each datum accordingly. This 
is an awkward and somevihat difficult task to program in either FORTRAN 
or COBOL. 

Althoixjh there are short cuts (a subroutine package for example) , the 
application programmer becomes more concerned about device 
characteristics than with the application to be acccmpl ished. 
Furthermore, once the application program is written, changing the 
format of the terminal screen definition described within the 
application program is difficult. The application program must often 
be rewritten if another type of terminal device requires support. In 
summary, program maintenance using this approach is time-consuming and 
costly. 

An alternative solution to terminal I/O being controlled by the 
application program is the Prime FORMS management system. FORMS allows 
the user to describe data formats in a forms description language 
(refer to Section 3). This definition language is completely separate 
from the application program. The form definition serves as an 
interface between the application program and the page-oriented 
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Figure 2-1. Flow of Instructions and Data between 
Terminal Screen, FOPMS Descriptor, and Applications Program 

Data Area. 
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teminal device in use. The forms definition describes each data field 
transferred (input) to or (output) from the application program by its 
position in the input or output data record and further relates this 
description and position to the field's position on the terminal 
screen. FORMS also relates other information such as the field's 
length, display attributes (blink, reverse-video, write protected, 
etc), justification, validation - if any, etc. Data is transferred 
between the application program and the terminal using standard input 
and output statements (for example, READ and WRITE). 

USING FORMS 

FORMS consists of three components. A form definition language 
translator (FDL) translates source form definitions into a usable form. 
A catalog maintenance tool, the Ebrms Administrative Processor (FAP), 
is used to update a system-wide FORMS directory that contains all tonn 
definitions available for use by application programs. Finally, the 
FORMS Run-time System Library is a collection of subroutines that are 
invoked by FQRi'IS directives and interact with the application programs 
and the terminals to provide I/O handling at execution time. 

FORMS is device independent. The user may define a form to be 
displayed on any terminal and/or system (spooled) line printer. (FORMS 
WDrks with any page oriented device, hard or soft copy.) Multiple 
teminal types may simultaneously run the same application program, 
since pJiysical device selection is deferred until execution time. 

To use FORMS, the user must have a teminal that has field 
write-enable/protect, absolute cursor positioning, and block-mode 
transmission cap)abiiities (refer to Appendix B) . FORMS currently 
supports the VISTAR3 and OWL1200 devices and system line printer. If 
the user wishes to use a nonstandard teminal, only a device driver 
subroutine need be written following the guidelines set fortli in 
Appjendix B. 

FORMS DIRECTIVES 

The only difference between a "nomal" program and a FORMS application 
program is the inclusion of one or more FORMS directives. FORMS 
directives consist of keywords preceded by a double p»und sign, for 
example, ##INVOKE. These directives are embedded in standard language 
constructs. In FORTRAN, the directives are enclosed in quoted ASCII 
strings in FORMAT statements. For example, 

WRITE (6, 100) 


100 FORMAT ClflflNVOKE SCREENl') 

As demonstrated in the previous example, FORMS operates on a single 
file unit (default is 6) for screen device I/O. All I/O to the device 
takes place on that unit. 
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In the FORMAT statement example, the FORMS directive causes a character 
string to be passed to the I/O processor. This strirg is intercepted 
for special handling (the double pound sign is the token that prcmpts 
this interpretation). Ihe ##INVOKE directive, v^en intercepted, causes 
a call to be made to the FORMS run-time subroutine library, and the 
function of INVOKE is performed, namely the form descriptor named 
SCREENl is opened and written to the user terminal. Ihereafter, every 
transaction of file unit 6 is controlled by the FORMS library file 
known as SCREENl. Sections 3 and 6 discuss more about forms 
descriptions and how to create and install them. 

Run-time directives are the link between the application program, the 
catalogued form descriptions, the terminal configuration, and the 
terminal device drivers. For example, one directive selects a form for 
a particular application (##INVOKE). Directives pass all data fields a 
FIELD or FORMAT at a time, check validation status of input fields, 
clear displayed data fields, and change data field attributes during 
program execution. The available run-time directives and their 
functicais are discussed briefly in Table 2-1. For a detailed 
discussion of the run-time package, refer to section 4. 


EROGRAM EXAMPLES 

Section 7 gives an example program written in FORTRAN and Section 8 
gives an example progran written in COBOL. 
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Table 2-1. Sunmary of FOPMS Directives 


##B LINK/# #N(B LINK 

Blinks a designated field (##BLINK) or turns off 
blinking (##NOBLINK) feature. 

##CLEAR 

Clears unprotected (i.e., variable) data field 
displayed on the user terminal. {##CLEAR ALL 
clears all unprotected fields.) 

##DISPIAY/##NODISPLAY 

Displays field v4ien form is output (##DISPIAY) 
or does not display field (##NODISPLAY). 

##FKEYS 

Enables (##FKEYS ON) or disables (##FKEYS OFF) 
user function keys input at the terminal. 

##F0R2EREAD 

Forces FORMS to wait for and process user input 
at the terminal. 

##INVOKE 

Defines the form definition to be used (needed 
at least once in every applications program). 

##FRINT 

Allows output of current form and sends data to 
a printer. 

##POSITION 

Specifies field to v^ich the cursor at the 
terminal will be positioned on the next read 
operation. 

# #PROTECT/# #NOEROTECT 

Write-pfotects a designated field {##PROTECT) or 
ranoves protection (##NOPROTECT). 

##RELEASE 

Specifies that the current form definition is no 
longer to be used. 

##RVIDEO/# #NVIDEO 

Displays field in reverse video (##RVin;0) or 
normal video (##NVIDBO) . 

##SUBSTREAM 

Defines a substream to be processed by the next 
read or write statement. 

##VALIEATE 

Causes the return of validation status for all 
input data. 
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SECTION 3 

DESCRIBING DATA USED BY FORMS 


PURPOSE OF DATA DESCRIPTION 

Video terminals have a great potential for simple, powerful data entry 
and retrieval. Such features as page mode, cursor control, reverse 
video, and blinking can improve the speed and convenience of data 
terminal use. However, use of these features places a burden on the 
application program. 

The Prime FOFMS software package makes a terminal with page mode and 
cursor control look like any ASCII input-output device (as far as the 
application program is concerned.) Terminal input-output data is 
exchanged a record at a time by the normal I/O rules of the language in 
v^hich the application program is written. The inpnjt and outpxit formats 
of the data transferred to and from the terminal and the computer 
system must be indicated to FORMS (and the application program). With 
FORMS, the templates of the form and the data do not have to be 
specified internally in the application program. Instead, form and 
data descriptions are specified externally by the user and translated 
by the Ebrms Definition Language (FDL) command. 

FOPM DEFINITION 

A form definition describes user and terminal data formats. The form 
definition is divided into tWD p>arts. The first part describes the 
inpxit/outpajt data record. This descriptor gives the location of each 
data item in the record as well as some information about each data 
item in the record. The second part of the form definition describes 
how each of the data items (or fields) are displayed at the terminal. 
A typical form definition is discussed in the following p)aragraphs. 

Consider the design of a simple inquiry program that uses FOFMS to 
display entries at the terminal from a keyed index file. Program 
operations consist of entering an employee-id nunber at the terminal. 
Using the given anployee-id, the program performs a file look-up and 
displays the information to v\^ich the employee-id pertains. If the 
employee-id entered is zero or spaces, the program will exit to PRI140S 
command level. 
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Colimns 

item name 

data type 

1-4 

employee-id 

numeric 

5-34 

employee-name 

alphabetic 

35-64 

street-address 

alphanumeric 

65-84 

city 

alphabetic 

85-86 

state 

alphabetic 

87-91 

zip-code 

numeric 

92-103 

phone 

numeric / special 


Graphically, the above 
definition as follows: 

listed data wDuld 

appear 

in the 

data 

record 

1—4 5-34 35- 

-64 

65—84 

85-86 

87-91 

92— 

103 

1 id 1 name | address | 

city 1 

state 

1 zip 1 

phone 1 


This information illustrates the first part of the form definition. 
This part is known as the data stream descriptor . The data stream 
descriptor contains STREAM descriptor fields that describe each item in 
the user's input/output data record(s). The data strean descriptor 
must include the length of each item, and either implicitly or 
explicitly include the position of each item within the data record 
(i.e., the starting character position must be known or must be capable 
of being determined). The field descriptor(s) may optionally include a 
justify specification. fORMS provides for left-justification, 
right-justification, or centering. FCRi'lS also provides a zero-fill or 
space-fill option when entering data with justification. FORMS 
validates input data under a specified validation mask, or series of 
masks, and allows the user to correct the data if it is incorrect. 

Hie next task to be accomplished in the example inquiry program, 
previously discussed, is to design the FORMAT of the data displayed at 
the terminal. The display size (number of columns and lines available) 
must be taken into consideration. Attributes like write-enabled, 
blink, noblink, reverse video, or normal video that may be applied to 
each data field must also be considered. Finally, the length of each 
field displayed at the terminal must be specified. Ihis parameter may 
differ from the length of the correspondirg field in the input or 
output data record. In addition, v^ien considering the length of fields 
display^ at the terminal, any field proximity restrictions imposed by 
the device must be taken into account, for example, some terminals 
require fields be separated by one or more blanks. 

Vhile assigning jAiysical device positions and attributes for each data 
field in the data STREAM descriptor, the user may also specify titles 
(i.e., literal data) in tlie form definition v*iich is displayed at the 
terminal along with the application program data. This literal data 
usually describes or identifies data fields that follow. 
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The informaticn used to construct the second part of the form 
definition is known as the device format descriptor . An example of 
this type of information is shown by the following table: 


line 

column 

content 

length 

attributes 

2 

2 

'EMPLOYEE ID' 

11 

write-protected 

2 

20 

employee-id 

4 

write-enabled 

4 

2 

'NAME' 

4 

write-protected 

4 

20 

employee-name 

30 

write-protected 

6 

2 

'ADDRESS' 

3 

write-protected 

6 

20 

Street-add ress 

30 

write-protected 

7 

20 

city 

20 

write-pro tected 

7 

45 

state 

2 

wr ite-protected 

7 

50 

zip 

3 

write-protected 

9 

2 

'HUME PHONE' 

12 

write-protected 


According to the information in the foregoing list, v^en the form is 
written to the terminal at application program run-time, the 
information should appear as follows: 

*....2....*....3....*....4....*....5....*.... 


1 

2 

3 

4 

5 

6 

7 

8 
9 


EMPLOYEE ID 

NAME 

ATORESS 

HOME PHONE 


****Vlr ************************* 

****************************** 
******************** ** ***** 

************ 


The line and column markers in the illustration have been provided for 
ease of position identification. They do not appear vhen the form is 
displayed at the terminal. The underline characters repre^nt 
write-enabled data. Write-enabled data may be modified at the terminal 
by the user by typing new information in the appropriate field. The 
asterisks in the illustration represent write-protected data, viiich may 
not be modified by the user at the terminal. 


SUMMARY OF FORM DEFINITION 

This section gives information on how a form is specified and how to 
use the FDL conmand to translate the FDL source input. With FOWlS, the 
data fields within a form are stored as a stream and must be converted 
to some format to be displayed at the user's terminal device. 

A format indicates the locations on a terminal screen vihere literal 
text and variable data are to a{p)ear. 
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A stream indicates the mapping of the fields passed to and fran the 
data record (in the files maintained by the application program) and 
those fields displayed on the terminal screen. 

Tagether, the STREAM and the FORMAT are called the form definition. 
MAPPING 

Mapping establishes a correlation between a STREAM descriptor field and 
a FORMAT descriptor field. Mapping binds the record position and item 
(field) length information etc. contained in the STREAM field to the 
terminal device position and display attribute information contained in 
the FCSMAT field. 

Fields in the data STREAM descriptor are mapped by name to 
corresponding fields in the FORMAT descriptor. These field names need 
not match the data nanes used within the application program, but 
common sense and good prograitining practice dictate that the user 
should, vAiere practical, keep names as closely matched as possible. 
For example, a data item called EMPLOYEE-NAME in a COBOL program might 
be represented by a FIELD called EMPLNAME in a form definition. There 
is an eight-character maximun for names within FORMS. 

STREAM descriptor fields that are mapped (some are not, refer to 
Section 5) contain the name of the FORMAT descriptor field to v«hich 
they map in the body of the FIELD definition. Therefore, FORMAT 
descriptor FIELDS are mapped to STREAM descriptor FIELDS and are also 
assigned a name by the associated STREAM descriptor FIELD. TWo fields 
are bound when the name specified in the STREAM descriptor FIELD and 
the fieldname specified in the FOMAT descriptor FIELD are identical. 
A bound field contains all available information regarding the data 
therein; i.e., its record and terminal device position and length, 
justification, validation, and display attributes. 

Because the two parts of the form definition are described separately 
in The Fonn Definition Language (FDL), they must be in some way related 
to each other. Since STREAM fields are mapped to FORMAT fields, so are 
STREAM descriptors mapped to FORMAT descriptors. Each data STREAM 
descriptor has an associated unique name. When the application program 
uses a form definition, it is identified by this name. FORMAT 
descriptors that correspond to a particular STREAM descriptor are 
assigned an identical name. 

Refer to the sample STREAM and FORMAT previously discussed. The STREAM 
descriptor.name must be the same as the FORMAT descriptor name. For 
example, the STREAM descriptor FIELD describing the employee-id must 
map to the FORMAT descriptor FIELD containing the employee-id. 
Likewise, the STREAM descriptor FIELD describing the employee-name must 
map to the FORMAT descriptor FIELD describing the employee-name, and so 
on. 
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DESCRIBING DATA 


FORM DESCRIPTOR PREPARATION 

The STREAM and FORMAT are coded in Forms Definition Language. This is 
the source input to the FDL translator. Tiie source input may be 
prepared using the PRIMOS text editor (ED) and may be placed into a 
file. For information on the editor (ED) , refer to the New User's 
Guide to Editor and Runoff. Ihe STREAM and FORMAT descriptors are 
translated by the FDL translator. When translated, the object output 
is placed in the FORMS catalog using the FAP command. (For further 
information, refer to Section 6.) 

Coding a FORMAT 

Figure 3-1 shows a simple screen layout, amd the associated FORMAT 
coding needed to define the terminal screen layout that is illustrated. 

From the example shown in Figure 3-1, it is possible to derive some 
guidelines of how a FORMAT is defined. 

• The input line is generally free-format. 

• FORMAT descriptors and FIELD names must start in colunn 
(character position) 1 and be followed by a space. 

• FIELD and FORMAT names must be from 1 to 8 alphanuneric 
characters (A-Z, 0-9). 

• FIELD statanents may start anyv^ere after colunn 1 and may 
occupy colunns 2-72. 

• Colunns 73-80 are ignored by FDL. 

• Items in an FDL source input line may be separated by a space 
or a comma. 


Figure 3-1 also shows some of the fields specified as NOPROTECT. It is 
a useful practice when specifying a field having the NOPROTECT 
attribute, to allow two (2) screen positions either side of the 
NOFROTECTed field for possible insertion of control characters. 

The boundaries of a FORMAT descriptor are a FORMAT statement arri an END 
FORMAT statement. Within the FORMAT definition, there must be at least 
one DEVICE statement and an associated EM) DEVICE statanent. Within 
the definition of a DEVICE, there may be as many FIELD statements as 
are necessary to define the form. FIELD statements define both literal 
and variable (NOPROTECTed) fields. Optionally, REPEAT and END REPEAT 
statements may be included as desired within the boundaries of a DEVICE 
definition to define similar fields V(*iich are repeated a number of 
times on a form, for example, part nunbers and part descriptions on a 
parts list. 
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INFILE FORMAT 

DEVICE OWL1200 

FIELD 'NAME' POSITION (21,8), REVERSE VIDEO 
FIELD '; ' POSITIC»l (25,8) 

NAM FIELD LENGTH 16, POSITICW (38,8) , NOPROTECT 
FIELD 'DATE' POSITION (21,10), REVERSE VICEO 
FIEID ': ' POSITION (25,10) 

DAT FIELD lENGTH 6, POSITION (38,18), NOPROTBCT 

FIELD 'PROFESSION' POSITIOI (21,12), REVERSE VIDEO 
FIEID ': ' POSITION (31,12) 

PRCF FIELD LENGTH 12, POSITION (38,12), NOFROTECT 
END DEVICE 
END FCRI^AT 


Figure 3-1. Sample FORMAT Code and Screen Display. 
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DESCRIBING lATA 


Ccxling a STREM 


Figure 3-2 shows a simple data record layout and the associated STREAM 
coding needed to define the data record used by the application program 
to store the form within the record. From the example shown in Figure 
3-2, it is possible to derive some guidelines about how a STREAM is 
coded. 

There is a slight alteration on the appearance of a FIELD statement in 
a STREAM descriptor, compared to a FIELD in a FORMAT descriptor. 
Examination of Figures 3-1 and 3-2 reveals the relationship that the 
FIELD names used in the FORMAT must be the same as the identifiers in 
the FIELD statements in the STREAM specification. Also, the FORMAT 
name and the STREAM name are the same. This parallelisdi of names is 
called mapping , and has been discussed in previous paragraphs. The 
reason for mapping is to associate the data items in fields on the 
screen with their counterparts in the fields stored in the data record 
within the computer system. 

The guidelines for coding a STREAM are essentially the same as for 
coding a FORMAT. The same rules hold for STREAM descriptors as for 
FCfftt'iAT descriptors. 

A STREAM descriptor begins with a STREAM statement, and ends with an 
END STREAM statanent. The only other kind of statements needed within 
the body of a simple STREAM are FIELD statements. However, these FIELD 
statements need not have names - though they can - but must have an 
identifier within the FIELD statement that maps to the same FIELD name 
in an associated FORMAT descriptor. Optionally, REPEAT and END REPEAT 
statements may be used as needed to lay out the description of fields 
in the data record that are repeated a number of times. 

Wien coded, the STREAM is translated by FIX.. The next portion of this 
section discusses translation. 

TRANSLATING STREAM AND FCRMAT CODING 

Tb translate a source form definition, the command is: 

FDL filename 

filename is the name of the file that contains the source text of the 
F(X?MAT and STREAM produced by the user. For example: 


OK, FDL DATASl 
GO 

0000 ERRORS (FIX., REV 16 - 16-^’EB-79) 
0000 ERRORS (FDL, REV 16 - 16-FEB-79) 

OK, 
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NUMBER OF BYTES (CHARACTERS) 

16 6 12 



DATA RECORD 
DESCRIBED BY 
STREAM FILE 


INFILE STREAM 

FIEID NAM LENGTH 16, NOPROTECT 
FIELD CAT LENGTH 6, NOPROTECT 
FIELD PROF LENGTH 12, NOPROTECT 
END STREAM 


Figure 3-2. Sample Data Record layout and STREAM Coding. 
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DESCRIBING DATA 


Ihe FDL translation produces a binary-form object file and a listing 
file named B_filename and L_filename, respectively. The above exanple 
produces an object file named B_DATAS1 and a listing naned L_EATAS1. 

FDL Output Listing 


The listing file for a FCRMAT translation provides a listing of the 
statements within the F0RI4AT descriptor and a diagram of the FORMAT 
that is translated. 

The listing file for a STREA/'I descriptor also provides a listing of the 
statements within the STREAM descriptor. This listing always specifies 
both an input STREAM descriptor listing and an output STREAM descriptor 
listing. If not otherwise specified, all STREAM fields are considered 
to be INPUT/OUTPUT. 

Exanples of the output listing from FDL will be found in Appendix F and 
Appendix H. 

Table 3-1 lists the options available for use with the FDL command. 


Option 


Table 3-1. FDL OPTIONS 
Meaning 


-OBJLIST 

hMACLIST 

-ERRLIST 

-ERRTERM 

-REPLIST 

-NOMACLIST 

-NOERRTERM 

^^OREPLIST 


Produce listing with translated code represented in octal. 
Lists macro expansions. 

List lines containing ERRORS only. If errors are present, 
this option overrides all others. 

Display (or print) lines containing errors at the user 
terminal. 

Generate expanded REffiAT block listings. 

Suppress expand macro listings. 

Suppress error output to terminal. 

Suppress expanded REPEAT block listings. 
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FC»MS RUN-TIME PACKAGE 


SECTION 4 

FORMS RUN-TIME DIRECTIVES 
REFERENCE INFORMATION 


FUNCTION 

Ihe FORMS run-time package provides a series of directives to perform 
all form definition lookup, directive processing, data manipulation, 
and device input/output (refer to Figure 4-1). 

The directives available in the FOFMS run-time package are listed 
below. The following directives are generally concerned with form and 
data input-output; 

##CLEAR 

##FKEYS 

##FORCEREAD 

##INVOKE 

##POSITION 

##PRINT 

»#REIi:ASE 

##SUBSTREAM 

VALIDATE 

In addition, there are a nunber of FORMS directives that control the 
manner in v^ich fields are displayed at the terminal. Tiiese are: 

SSBLINK/»#NOBLINK 
ft #DISPLAY/ft ftNODIS PLAY 
ft#PROTECT/ft ftNOPROTBCT 
ftftRVIDEO/ftWVIDEO 

USA® 

The application program passes to FORMS any statement that contains a 
forms directive. A FORMS directive is written with twa preceding hash 
marks (ft#) in order to be identified by the program as a FCKMS 
directive. These directive are extensions of the source programming 
languages in vftiich the afplication program is written. 

For example, to invoke form FD4190 on the terminal and protect fields 
FIELDA, FIEEIB, and FIELDC, a FORTRAN application program WDuld execute 
the following directives; 

WRITE (1,400) 

400 F0R4AT CftftlNVOKE FD4190'/ 

+ 'ftftPROTECT FIELDA, FIELDB, FIELDC') 
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Figure 4-1. FORMS Run-time Package Functional Relationships. 
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FORMS RUN-TIME PACKAGE 


DESCRIPTION OF DIRECTIVES 

Ihe following paragraphs describe all directives available in the FCffMS 
run-time package. For clarity, ttey are depicted in upper-case 
characters. Lower-case characters in FORMS directives are mapped to 
upper-case. 


► ilfCLEAR [ALL] 


The ##CLEAR directive clears all unprotected data displayed on the user 
terminal. It also causes all data items marked as NOFROTECTed and 
displayed in the input/output list to be reset to spaces. This is a 
fast and convenient method to erase all user-input data. Alternately, 
spaces may be written to all unprotected fields on the form. If the 
#ifCLEAR directive is followed by the word ALL, the entire display is 
erased. This should be done only prior to issuing a sIreleaSE 
directive. 


#|[CLEAR Examples 


WRITE (1,4000) 

400 FORMAT ('#ffCLEAR') 


C-CLEAN UP BEFORE EXITING TO CCMMAND LEVEL. 

C 

WRirE (1,5020) 

5020 FORMAT ('WLEAR ALL'/ '##RELEASE') 


|off) 

^ ##FKEYS [ON j 


Tne IfftFKEYS directive enables, or disables, user function key input 
fran the terminal. If ##FKEYS is followed by the parameter OFF, the 
function keys at the teminal keyboard are disabled; if folloved by 
the parameter ON, function keys are enabled. 

Wien function keys are disabled, they have no effect if entered. The 
standard response is to place a warning message on the terminal and 
wait for the user to press the trananit key. When a form is invoked, 
an implicit ##FKEYS OFF directive occurs. 
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When function keys are enabled, a two-digit code is automatically 
appended to each input record following the right-most FIELD defined in 
the STREAM or SUBSTREAl'1. Ihis field contains the nunber of the 
function key that was pressed when the data was transmitted from the 
device. If the normal trananit key was pressed, this field contains 
00 . 

If multiple siiDstreams are described in the form definition, the 
function key nuonber is appended to each. 

It is the user's responsibility to ensure that the two character 
positions required for the functicai key field are available at the erx3 
of each input record. If these twD character positions are not 
available, the function key nunber is not returned. 

The application program may define each function key to perform some 
special escape function, such as request a new form definition, exit 
program, perform a database update with the new data entered on the 
terminal, etc. 

The user must not write an application program that makes use of 
function keys unless all terminals that are to run the program are 
equipped with function keys. 


► if#FORCEREAD 


The If IfFORCEREAD directive forces FORMS to wait for and to process user 
input from the terminal, thus providing a facility to override the 
normal input protocol v^ien processing a form definition with multiple 
substreams. Normally, terminal input occurs when the application 
program (1) executes the first read statement after the form is 
invoked, (2) issues a read statement following a write statement, or 
(3) attempts to read a substream that has already been read. The 
FORCEREAD directive causes terminal input on the next read operation, 
whether or not the next substream to be processed has already been 
read. 


iffrFORCEREAD Example 

WRITE (1,200) 

200 FORMAT (' If frFORCEREAD') 

READ (1,210) IREC 
210 FORMAT (32A2) 
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FORMS RUN-TIME PACKAGE 


^ ##INVOKE fonnname 


The ##INVDKE directive defines the form definition to be used. It is 
followed by the form (stream descriptor) name, tormname . 

When the ##INVOKE directive is issued, FORMS searches the catalog for 
the specified form definition. If found, it is read into memory and 
initialized. If not found, an error message is printed and return is 
made to FRMOS command level. When a form is invoked on a device, all 
input and output requests for that device are trapped and handled by 
the run-time package. When the fonn definition is subsequently 
released, all I/O is handled by calls to IOCS subroutines. (Refer to 
the Subroutine Reference Guide. 

If a previous form definition was invoked and not released before 
issuing the current ##INVOKE directive, an implied release of the 
previous form definition occurs. 

##INVOKE Example 

WRITE (1,120) 

120 FORMAT ('##INVOKE TAXD01') 


^ ttPOSITION 


The DEPOSITION directive allows the specification of the field to viiiich 
the cursor will be positioned on the next read operation. This command 
is only applicable to the next read operation; subsequent read 
operations position the cursor to the first NOPROTECTed character 
position on the terminal, unless subsequent DDPOSITION coiTunands are 
issued. 

DDPOSITION Example 

C-POSITION TO FIELD SPECIFIED BY CCNTENTS OF 'FL[»JAM' . 

C 

WRriE (1,250) FLDNAM 
250 FORMAT ('D#POBITICN ', 4A2) 


^ DDPRINT formname [LOCAL] 


The DDPRINT directive allows the user to print the current form and 
user-entered data trcm the terminal to either the spooled line printer 
or a local printer attached to the individual terminal. This permits 
the program to print the current transaction on a hard-copy device 
without defining a separate FORMAT descriptor for the line printer. 
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If the parameter ICCAL is included in the frfrPRINT directive, the form 
is printed on vi^atever hardcopy device is attached to the terminal. If 
the LOCAL parameter is not given, the copy is spooled for printing on 
the line printer. If a spiecial paper form is needed by the line 
printer, it must be mounted by the operator. 

##PRINT Examples 

WRITE (1,200) /*WRITE TRANS. TO SYS PRINTER 

200 fORMAT ('##PRINT') 


^ # RELEASE 


iTie ififRELEASE directive specifies that the current form definition is 
no longer to be used. All I/O is processed via calls to IOCS until the 
next HINVOKE directive. 

##RELEASE Example 

WRITE (1,900) 

900 FORMAT (' # IfRELEASE') 


► ##SUBSTREAM streamname 


The MSUBSTREAM statement defines the siiostream to be processed on the 
next READ or WRITE directive in the host language. The SUBSTREAM nane 
streamname must follow the directive and be separated fron it by at 
least one space. If the named SUBSTREAM does not exist in the STREAM 
descriptor, an error message is generated and the program aborts. 

fttfSUBSTREAM Exanple 

WRITE (1,200) 

200 FORM ('lt#SUBSTREM NAMADER') 


^ #)fVALIDATE 


The iffVALID^TE directive causes the run—time package to return the 
validation status of all input data on encounterirg the next READ 
statement(s) . 
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The status is returned in the form of a two-digit nunber for each 
input/anpty-conditional (see Section 5) or direct field (see Section 5) 
that is not declared as output-only. It is not returned for 
input-literal fields. The two-digit number returned represents one of 
the followirg conditions; 

Number 

Range Condition 


<0 The data failed all validation tests. (Value usually -1, 
in this case. 

00 No validation specified for this field. 

>0 Ihis is the nunber of the first validation mask 

that the data passed. Validation masks are nunbered 
in the order in v^ich they appear in the FIELD 
definition. 

The validation status is returned in the same manner tliat data is 
returned on a READ statement. If there are multiple SIBSTREAM 
definitions, the user must do multiple READS to input the validation 
status for all fields. The ##VALIDATE directive causes the next READ 
statement to input the validation status of the first SUBSTREA(4 in the 
STREAM descriptor unless a ##SUBSTREAM directive is issued before 
#|fVALIDATE. The SftVALIDATE function is disabled and normal data input 
resuned when either the end of the STREAM descriptor is encountered or 
a IflSUBSTREAM or ##FORCEREAD directive is issued. 

VALIDATE Example 

C-INPUT FIELD VALIDATION. FIRST SUBSTREAM CONTAINS 5 INPUT 

C FIELDS, SECOND CONTAINS 4. 

C 

WRITE (1,300) /* POS TO FIRST SUBSTREAM 
300 FORMAT ('##SUBSTREAvl ONE'/'if#VALIDATE') 

READ (1,310) (IVAL(I),1=1,9) /* READ VALIDATION 

310 FORMAT(5I2/4I2) 
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ATTRIBUTE MODIFICATION DIRECTIVES 


The application program may dynamically change the attributes of a 
field by issuing one of the attribute directives. From one to twenty 
stream descriptor field names may be placed as argunents, each 
separated by at least one space. The modification occurs at the next 
WRITE or READ in v*iich data (as opposed to FORMS directives) is 
transferred to or from the device. 


The following table describes each of the eight attribute-modification 
directives and three synonyns. 


Statanent/Synonym Description 


DttPROTBCT 
#NOreOTECT/ENABLE 
HRVIDEO 
##N VIDEO 
»#BLINK 
##NCBLINK 
##DISPLAY/reEE 
lf#NODISPLAy/HOLD 


write-protects field 

write-enables field 

field displayed on reverse video 

field displayed in normal video 

blinks field v\hen displayed 

field is displayed vdien form is output 

field is displayed when form is output 

field is not displayed when form is output 


Example ; 

WRITE (1,300) 

300 FORMAT (’#ltPROTECT NAME, IDNIMBER, ADDRESS'/ 
+ '##NOPROTECT REMARKl REMARK2 REMARKS') 


PROGRAMMING CONSIDERATIONS 
Run-time File Handling 

FORMS usually requires only one file unit for all file I/O. This unit 
nunber is assigned dynanically and is the first available file unit not 
already open. 

The only exception is for the systan printer device driver. TO copy 
files into the spool queue, twD file units are required. Units 15 and 
16 are used by PR$IO. To allocate two other units, modify variables 
FUNITC (=5), PRINFO(l) (=15), and PRINF0(2) (=16) in the file 
FCRMS>IOS>PRO$IO. All are declared in DATA directives. 


REV. 0 


4 


8 



PI]R3040 


FORMS RUN-TIME PACKAGE 


Run-time Error Handling 


Run-time error diagnostics generated by FORMS are self-®{planatory. 

Error message text is stored in the file FORMS*>RUN.ER. Each line in 
the file is preceded by a numeric key, between 1 and 9999. If a 
diagnostic requires more than one line (as do most), each following 
line contains the same numeric key as the first. The end of the 
diagnostic occurs when a line with a different numeric key is 
aicountered. 

The procedure that calls the FORMS error handler may supply from 0 to 3 
arguments. An argument is inserted into the error diagnostic v^en a 
percent sign (%) followed by a value (1-3) is encountered in the text 
string. 

The calling sequence for FORMS run-time error handler is: 

CALL EM$ERR (KEY, FSCODE, TEXTl, LENl, TE)Cr2, LEN2, TEXTS, LEN3) 
Parameter Memory 


KEY Numeric key of the error diagnostic to be printed. If 

this diagnostic is not included in the file, an error 
message is printed containirg the error number. All 
errors generated by fOMS have corresponding text 
messages in RUN.ER. 

FSCCOE The file system code associated with this error 
condition. If this error is not a result of a file 
system error, this value should be zero. 

TEXTh Text argument n. If not referenced by the error 

diagnostic, this need not be supplied. 

LENn Length in characters of the corresponding text 

argument. If this argument is not used, it may be 
omitted. 


Users who write their own device drivers may make use of this error 
handling facility. Numeric error codes (keys) i-999 are reserved. 
Users may allocate any error code above, and including, 1000. 
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Loading the Shared Library 

It is a system administration decision v^ether or not to support the 
shared libraries. If shared FORMS is supported, shared CCBOL, MIDAS 
(KI/tA on master disk) , and FORTRAN must be supported as well. if 
shared libraries are in use, the F0R4S shared library file will be 
named VFORMS. 

Configurable I/O List 


The FORMS run-time package contains a fixed length buffer, called the 
I/O list that holds the current form definition. The default I/O list 
size is 2500 words (decimal) . If the user runs a program v\hich invokes 
a form that exceeds this capacity, FORMS prints the error message; 

REQUIRED= nnnn, AVAILABLE= 2500. 

I/O LIST OVERFLOW. 

The user may allocate a larger I/O list in his (FORTRAN) progran by 
inserting the following three statements: 

PARAMETER IOLSIZ=desired_size 
COMMCW /IOBCM$/ IBUF(3) , lOL (lOLSIZ) 

DATA IBUF /lOLSIZ, 0, 0/ 

All items are 16 bit integers. 

The COBOL user may enlarge the I/O line size used in his COBOL program 
by writing a short FORTRAN subprogram (statements start in column 7); 

SUBROUTINE name 

PARAMETER IOLSIZ=desired_size 

CQvlMOJ /IOBCM$/IBUF(3) ,IOL (lOLSIZ) 

DATA IBUF/IOLSIZ,0,0/ 

END 

Compile this subprogram with the FORTRAN compiler. When loading the 
main COBOL pr^ram, load this FORTRAN subprogram's binary module 
(B_name) containing the redefinition of the I/O list prior to loading 
the FORMS library. 

Ihe user may also modify the default buffer pool size by charging the 
'lOLSp' declaration in ' FORMS >RUN>IOLDEF' and re-compiiing the 
run-time system, using the appropriate tools provided on the master 
disk. Refer to the System Administrator's Guide. (This should be done 
under the direction of a system administrator or senior systems 
analyst.) 

This feature is not available v^hen using the 64V mode shared FORMS 
library; however, the default size for the shared library is 7000 
words. 
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SECTION 5 

FORMS DEFINITION LANGUAGE, 
REFERENCE INFORMATION 


This section defines the data definition language (FDL) that is used to 
describe to the FORMS system the data formats discussed in Sections 1 
through 3. 


SYNTAX OF FORMS IXIFINITION LANGUAGE 
Statements 


FDL supports a free-FORMAT statement line. 

All descriptor, substream, and field names start in the first character 
position of the line and are followed by at least one space. Data 
STREAM and device FORMAT descriptor statements may start anyi^ere after 
column 1 and occupy colunns 2 through 72. Columns 73 through 80 are 
ignored. Items in the FOL, input line must be separated by either a 
space or a ccwnma unless otherwise noted. Lower-case characters are 
mapped to upper-case, except characters in a literal string (enclosed 
within single quotes). 

If an input record contains too many characters to fit on one line, 
source text may be continued by placing a semicolon (;) at the end of 
the line. Input items (wards, text strings, etc.) may not be split 
across two lines. There is no limit to the number of continuation 
lines in a source record. There is, however, a 240 character limit per 
statement. 

Comments 


If the first character of a line is an asterisk, the line is treated as 
a ccsanment, listed in the output file and ignored. If the first 
character is a single quote (') the line is treated as a comment, but 
this line causes an eject page in the listing and becomes the new page 
header. 

In addition to full-line comments (lines beginning with an asterisk or 
single quote) , in-line conments are supported. In-line ccxnments are 
preceded by a fore-slash and asterisk (/*) and followed by an asterisk 
and a fore-slash (*/). If the in-line canment is the last item on the 
line, the terminating characters (*/) may be omitted. In-line comments 
may not occur within an item (e.g., in the middle of a name or text 
string). 
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Examples of Comments are: 

* THIS IS A COmENT LINE 

' THIS WILL CAUSE A PAGE-EJECT AND WILL BBCCME THE NEW HEADER 

LABEL FIELD ABC, LENGTH 6 /* THIS IS AN IN-LINE COGENT 

LABEL FIELD ABC, /*THIS TOO IS AN IN-LINE COMMENT*/ LENGTH 6 

NAME FIELD 'FOUR SCORE AND SEVEN YEARS AGO... ' ; 

POSITION (10,10) PROTECT/* CONTINUATION LINE 

Naming Conventions 


The rules for naming FORMS descriptors, fields, and substreams are: 

• name length; 1-8 characters 

• first character must be alphabetic 

• permitted characters: A-Z, 0-9 

Examples of form descriptor names are; 

Example Corment 

GAZORKLEFORM name too long 

SHIPFORM val id 

5F0RM bad first character (5) 

FORMS val id 

CWED$ illegal character (S) 

A'^TOWED val id 

Descriptor Structure 


Figure 5-1 represents various form definition structures for both the 
STREAM descriptor and FORMAT descriptor (refer to Section 3 for an 
overview of these descriptors) . 

Each statanent illustrated in Figure 5—1 is detailed in the paragraphs 
that follow. 

FO^ DEFINITION EELIMITER STATEMENTS 

The FDL statements described in this section are used to specify the 
beginnii^ and end of a form definition or a section of a form 
definition. These statements do not describe data formats but rather 
are used to identify STREAM and FORMAT descriptors, SUBSTREAM 
descriptions and DEVICE descriptions within a FORMAT descriptor. 


REV. 0 


5 


2 


PDR3040 


FORMS raiFINITION LANGUAGE 


Stream Descriptor 


STREAM statement STREAM statement 

. SUBSTREAM statement 


FIELD definitions -or- 

. FIELD definitions 


END STREAM statement 

END SUBSTREAM statement 
SUBSTREAM statement 


FIELD definitions 


END SUBSTREAM statement 
END STREAiM statement 


FORMAT Descriptor 


FOFMAT statement 
DEVICE statement 1 


FIELD definitions 


END DEVICE statement 
DEVICE statement 2 


FIELD definitions 


END DEVICE statanent 
END FORMAT statement 


Figure 5-1. Form Definition Statements. 
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STREAM Definition Statements 


^ name STREAM 


The STREAM statement defines the beginning of a STREAM descriptor. The 
n^e field begins in colunn 1 and must contain a unique stream 
descriptor name (i.e., one that does not conflict with any other stream 
descriptor defined within the system). For example: 

SHIPFORM STREAM 


^ END STREAM 


The END STREAM statement defines the end of a STREAM descriptor. For 
example: 

END STREAM 

^ name SUBSTREAM 


The SUBSTREAM statement defines the beginning of a substream 
description. The application program transfers data to and from the 
substream specified by name . (Refer to the introduction to substreams 
in Sections 3 and 4, and the example using substreams in Section 7, For 
example: 

USERDATA SUBSTREAM 


^ END SUBSTREAM 


The END SUBSTREAl^ statement terminates a substream description. Each 
SUBSTREAM statement must have an associated END SUBSTREAM statement. 
For example: 

END SUBSTREAM 
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FORMAT Definition Statsnents 


^ name FORMAT 


The FCH4AT statement defines the beginning of a FORMAT descriptor. Tbe 
contents of the name field defines the name of the format descriptor. 
The name must be equivalent to that of the stream descriptor with v^ich 
this FORMAT descriptor will be used. For example: 

USERDATA FORMAT 
► END FORMAT 

The END FORMAT statement terminates the FORMAT descriptor and must be 
the last statement in the FORMAT description. For example: 

END FORMAT 


DEVICE Definition Statanents 


^ DEVICE dev 

The DEVICE statement specifies the name of the device that is defined 
by the field definitions in the following FIELD statements, dev is the 
specified device name. This statement is used in the FORMAT descriptor 
immediately following a FORMAT or END DEVICE statement. For example: 

ADMN377 FORMAT 

DEVICE VISTAR3 

^ END DEVICE 

The END DEVICE statement defines the end of a device description within 
a FORMAT descriptor. For example: 

END DEVICE 
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FIELD STATEMENTS WITHIN A STRRAM EESCRIPPCH 

The fields defined within the STE^EAM descriptor by the FIELD statement 
identify; first, the location of each data item within the input or 
output record; second, its length; and third, optional justification 
and validation information. 

Stream fields may be defined to be INPUT only, OUTPUT only, or 
INPUT-OUTPUT, which is the default value. INPUT fields are processed 
on inpjut operations only, they are ignored on output. Ihe reverse is 
true for OUTPUT fields. INPUT-OUTPUT fields are processed on both 
input and output operations. Ifeing INPUT and OUTPUT fields, the 
programmer may describe separate input and output record formats in a 
single STREAM descriptor. 

FIELD Types 


Tliere are six types of OTREAi'i descriptor fields. Each type either 
describes an item within the user's data record or describes a literal 
strirg to be mapped to a field defined in the FORMAT descriptor. Ihe 
field types are described in the following paragraphs. 

Direct ; A direct field maps the data item in the input or output 
record to the named FORMAT descriptor field. Its format is as follows; 

FIELD fieldname 


Input Literal ; An input literal field returns a literal string to the 
data record on an input operation. It is ignored on output operations. 
Its format is as follows; 

FIELD 'literal text string' 


Output Literal ; An output literal field defines a literal text strirg 
to be mapped into a FORMAT field on output operations. It is ignored 
on input operations. No data is transferred to or from the 
input/output record. Its format is as follows; 

FIELD (fieldname,'literal text string') ,OUTPUT 
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Input Bnpty Conditional ; An input onpty conditional (IBC) field 
functions the same as an input or an input-output direct field with one 
exception - if the data field displayed on the device contains spaces, 
the supplied literal string is returned instead of blanks. lEC fields 
may not be output only. Also, lEC fields require an input-output 
specification (the value of iospec may be INPUT or INPUT-OUTPUT). Its 
format is as tollows: 

FIELD (fieldnane,'literal text string'), iospec 


Filler ; Fields defined as fillers perform no data transfer between the 
application program and the device. They only define a gap in the 
input or output record. On input and/or output operations, the nunber 
of characters designated by the LENGTH parameter in the filler field 
definition are skipped. A filler field's format is as follows: 

FIELD FILLER, LENGTH n 


System Information : A systan information field (SIF) acts like an 
output literal field. It is processed only on output operations and it 
maps data into a selected FORMAT field. The mapped data, towever, is 
not a literal text string but a system related piece of information 
like: current time, data, user name and nunber, or form name. The 
format of a SIF field is as follows: 

FIELD (fieldname,SIl;name) 


SIF names, contents, format, and length are described below: 


DATEl: 
DATE2: 
DATE 3: 
DATE4: 
TIMEl: 
TmE2: 
USERNME: 
USERNUM: 
FORMNME: 


date, YY/MM/DD 

date, ]X)-MMM-YY 

date, MM/DD/YY 

date, ro.MM.YY 

time, HH:MM 

time, HH:MM xM 

user login name, XXXXXX 

user number, NN 

form name, XXXXXXXX 


{8 characters) 


(9 " } 

{8 " } 

{3 " } 

{5 } 

{8 " } 

{6 " } 

12 " } 

{8 } 


Each field with a direct, an output literal, an empty conditional, or a 
system information field type is identified by a one-to-eight-character 
name that must be unique within this STREA4 definition. This nane may 
be supplied in the left margin of the field definition statement. If 
not explicitly defined, the field name is assumed to be the name of the 
format field to v^iiich the STREAM field is mapped. To modify any 
attributes of this field, the field name is given as a parameter to a 
fOFMS run-time directive (refer to Section 4) . 
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FIELD Parameters (for STREAM) 


The parameters discussed in the following paragraphs are position 
independent. They may appear in the field definition after the mapping 
or literal specification. 


LENGTH Parameter ; The LENGTH parameter defines the number of 
characters contained in the field. The keyword LENGTH must be followed 
by a positive non-zero integer. 


LENGTH Usage; The LENGTH parameter vAien used with the various field 
types has different effects with respect to its usage being required, 
optional, or assigned default values. These are summarized in the 
following list. 


field type 


remarks 


direct 

input-literal 


output-literal 
empty-conditional 
filler 
system-info 


required 

optional - if omitted, defaults to text 

string length; if supplied, text string 

is padded/truncated as required to meet 

given length 

same as input-literal 

same as input-literal 

required 

ignored 


JUSTIFY Parameter ; The JUSTIFY parameter defines the justification to 
occur v*ien any data is logically moved to this field. It must be 
followed by one of the following key words; 

NONE specifies no justification 
LEFT the field is left justified, right padded 

RIGHT the field is right justified, left padded 

CENTER the field is centered 


Note 


'JUSTIFY NONE' has the same effect as not specifying the 
JUSTIFY parameter. 

If justification is specified on both the STREAM and FORMAT descriptor 
fields, the data is justified according to the STREAM descriptor field 
specification on input and according to the FCSRMAT descriptor field on 
output. 
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JUSTIFY Usage: Ihe JUSTIFY parameter v^en used with the various field 

types has different effects with respect to its usage being required, 
optional, or assigned default values. These are summarized in the 
following list. 


field type 

remarks 

direct 

optional 

input-literal 

optional 

output-literal 

optional 

empty-cond i t ional 

optional 

filler 

ignored 

system-info 

ignored 


SPACE-FILL and ZERO-PILL Parameters : SPACE-FILL and ZERO-FILL are 

mutually exclusive parameters that define the fill character to be used 
when performing left or right justification. For each character 
position the data is shifted, either a space or zero is supplied on the 
end fron vAiich the shift is taking place. If the user enters the field 
with the data already right justified and right justification with 
zero-fill is specified in the form definition, left-most spaces (if 
any) will not be replaced with zeroes. If neither parameter is 
specified, SPACE-FILL is assumed. 

SPACE-FILL and ZERO-^’ILL Usage: 

See JUSTIFY Usage. 

INPUT, OUTPUT, and INPUT-OUTPUT Parameters : The INPUT, OUTPUT, and 

INPUT-OUTPUT parameters, which are mutually exclusive, define the 
direction of data transfer in vdiich the specified field is to be 
processed. 

INPUT/OUTPUr/INPUT-OUTPUT Usage: The INPUT, OUTPUP, and INPUT-OUTPUT 
parameters, v^en used with the various field types, have different 
effects with respect to their usage being required, optional, or being 
assigned default vali«s. These are summarized in the tollowing list. 


field type 


remarks 


direct 

input-literal 

output-literal 
empty-conditional 
filler 
system-info 


optional; default is INPUT-OUTPUT 
default to INPUT, if specified, must 
be INPUT 

must be specified as OUTPUT 

must be specified as INPUT or INPUT-OUTPUT 

optional; default in INPUT-OUTPUT 

ignored 
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VALID?^TE Parameter ; Ihe VALIDATE parameter defines the validation to 
take place on the field data vhen read from the device. The keyward 
VALIDATE is tollowed by one or more validation masks enclosed in single 
quotes and optionally separated by the ward 'OR'. 

v\ftien a field with a validation specification is transferred to the 
input record at run-time, the data is checked against the validation 
mask(s) supplied by the user. If all of the validation tests are 
passed, the next field is transferred to the input record. If the data 
fails all tests, FOFMS performs one of two actions specified by the 
FIX/NOFIX parameters. 

A validation mask consists of a string of characters, each defining a 
certain criterion tor the corresponding character in the field. If the 
length of the validation mask is less than that of the data field, the 
last character of the validation mask is logically repeated until the 
data field is exhausted. 

The validation mask characters and their meanings are: 

Mask CJiaracter Validation Criteria 

9 numeric (0-9) 

A alphabetic (A-Z, a-z) 

X aiphanuneric (0-9, A-Z, a-z) 

. period 

/ fore-slash 

B space (blank) 

$ dollar sign 

dash 

any character 

N numeric character (0-9, +, -, or blank) 

F floating numeric (0-9, +, -, ., blank) 

U unsigned integer (0-9, blank) 

P personal name (A-Z, a-z, ., ', or blank) 

Z alphabetic character or space 
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VALIDATE Usage: The A^LIDATE parameter v^en used with the various 
field types has different effects with respect to its usage beirg 
required, optional, or assigned default values. These are summarized 


in the following list. 


field type 

remarks 

direct 

optional 

input-literal 

ignored 

output-literal 

ignored 

empty-conditional 

optional 

filler 

ignored 

system-info 

ignored 

For example: VALIDATE 

•99.99' or 


FIX, NOFIX Parameters : When a field with one or more validation masks 
fails to meet any validation criterion, the programmer has a choice of 
forcing the F0R4S user to correct the data before FORMS returns it to 
the a^Jlication program. 

If FIX is specified, the data must pass one or more of the supplied 
validation tests before it is returned to the application program. If 
the data fails all validation tests, FCRMS prints an error message in 
the lower right corner of the terminal display and positions the cursor 
to the first character position of the field in error. The user at the 
terminal may then correct the error and re-trananit the information. 

If the NOFIX parameter is specified, the data is returned to the 
program v^ether or not it passes any of the validation tests. When the 
input record is complete, FORMS returns to the error return location 
instead of taking the standard return. An ERR= clause must be present 
in a FORTRAN read statement if any fields in the form definition 
contain a paragraph to do "error" processing. A validation error may 
be identified by either a FORTRAN or COBOL program by inspecting the 
two-character error code in the error vector by calling the GETERR 
system subroutine. (Refer to Subroutine Reference Guide) . FOERMS sets 
this code to VA tor validation errors. 

In most cases, it is convenient to require the data be in proper format 
v\^en it recjches the application program (i.e., using the FIX 
parameter), eliminating the task of inspecting multiple fields on a 
character-by-character basis. 

If FIX or NOFIX is not specified, FIX is assumed. 

FIX/NCFIX Usage: The FIX or NCFIX parameter v^en used with the various 
field types has different effects with respect to its usage being 
required, optional, or assigned default values. These are summarized 
in the following list. 
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field type 

remarks 

direct 

optional 

input-literal 

ignored 

output-literal 

ignored 

anpty-cond i t io nal 

optional 

filler 

ignored 

system-info 

ignored 


START Parameter ; The START parameter allows the user to specify the 
character position occupied by the first character of the data field 
within the input or output record. The the START parameter function is 
equivalent to that of the 'T' FORMAT descriptor in a FORTRAN FORMAT 
statanent. START allows overlapping of input/output fields, a function 
not available with the FILLER specification. 

The word START must be tollowed by an integer number that represents 
the absolute character position (within the user's data record) of the 
first character of the field. 

CAUTION 

If START is specified in an input-only field, the 
character pointer gets reset for the input record 
but not tor the output record. The inverse is true 
for output-only fields. This is reflected in the 
input and output STREAM descriptor tonnats 
generated by FDL, if the -lOFLIST option is 
specified. 

START Usage; The START parameter vhen used with the various field 
types has different effects with respect to its usage being required, 
optional, or assigned default values. These are summarized in the 
following list. 


field type 

remarks 

direct 

optional 

input-literal 

optional 

output-literal 

optional 

anpty-conditional 

optional 

filler 

optional 

system-info 

ignored 
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FIELD DEFINITION EXAMPLES: STREAM DESCRIPTORS 

The following FDL coding example shows how the types of STREAM 
discussed in this section are defined. The lines of code also show 
usage of some field parameters discussed. Before each field 
definition, a comment line has been inserted that identifies the type 
of field beirg defined. 

The following example code shows and example of definition of each 
type of field discussed and use of sane of the field parameters 
that are significant vhen used with the particular field types. 

* DIRECT FIELD TYPE. 

* 

FIELD IDNUvi, EDNGTH 5 

* 

* LITERAL INPUT FIELD, RETURN STARTING IN COLUMN 30 

FIELD 'LITERAL INPUT STRING', START 30 

* 

* OUTPUT LITERAL FIELD 

FIELD (HEALER,'HEAffiR TEXT') , OllTPUT 

* 

* INPUT EMPTY CCNDITI(»]AL FIELD TYPE 

FIELD (EMPLNAME,'NO EMPLOYEE NAME SPECIFIED'), ; 
INPUT-OUTPOT 

* NOTE USE OF SEMICOLON FOR FDL CONTINUATION LINE 

* 

* FILLER FIELD 

FIELD FILLER, LENGTH 12 

* 

* SYSTEM INFORMATION FIELD 

FIELD (0UrLIATE,,DATE3) 

* 

* INPUT-ONLY FIELD, JUSTIFY AND VALIDATE 

FIELD AGE, LENGTH 3, JUSTIFY RIGHT,, INPUT, ; 
VALIDATE '999' OR 'B' 
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FIELD STATEMENTS WITHIN A FOE^MAT DESCRIPTOR 

Fields defined within the FORMAT descriptor describe the appearance of 
data on the page-oriented device. This definition includes (1) field 
coordinates, (2) length, (3) justification, and (4) any display 
attributes to be associated with the data (e.g., write enable/protect, 
blink, reverse video, etc.). 

FIELD Types 

There are tw) types of FORMAT descriptor field statements; mapped and 
literal. These are described in the following paragraphs. 


Mapped ; A mapped field is actually mapped _to by a field defined in the 
STREAM descriptor. All mapped fields contain a 1-8 character name 
starting in the left margin in the field definition statement. The 
format of a mapped field is as follows; 

name FIELD field-name 


Any mapped field defined in the FORMAT descriptor and not mapped to by 
a STREAM field is ignored. Any STREAM descriptor field that maps to a 
nonexistent FOERMAT descriptor field is also ignored. 


Literal ; A literal field contains a text string specified in the 
FOFMAT descriptor field definition. Literal fields are used to supply 
tags (titles) for information displayed on the device and usually 
identify mapped fields. Ihe format of a literal field is as follows; 

FIELD 'literal text string' 


The literal data is specified innmediately following the FIELD statement 
and must be enclosed within single quotes. The name field (left 
margin) must be blank (no mapping is done from a stream descriptor 
field.) 


FIEID Parameters (for FORMAT) 

The following parameters may follow the FIELD statement in a mapped 
field and the literal specification in a literal field. They are all 
non-positional (i.e., they may occur anyv^Aiere in the field definition). 
All parameters apply to both the mapped and literal device descriptor 
field types. All parameters are optional unless otherwise noted. 
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LENGTH Parameter ; Itie LENGTH parameter defines the length of the field 
as it is to appear on the device. It must be followed by a positive 
non-zero integer that represents the field length in characters. This 
parameter is required on mapped fields and is optional on literal 
fields. If omitted, the field length is assuned to be the length of 
the literal string. 


The length of a field in the STREAM descrip»tor may differ from the 
length of a field in the FORMAT descriptor. The STREAM field defines 
the length in the input/output record of the aiplication program and 
the device format field length defines the length of the field on the 
input/output device. If they differ, the data is truncated or p>added 
as required. 

POSITION Parameter ; The POSITION parameter defines the position 
(colunn and line) of the first character in the field. The keyword 
POSITION is followed by the column and line (x,y) address, enclosed 
within parentheses and separated by a comma. This parameter is 
mandatory on both mapp)ed and literal fields. 

JUSTIFY Parameter ; The .JUSTIFY parameter defines the justification to 
take place when data is logically moved to (through) this field. Refer 
to the description of the STREAM descriptor field JUSTIFY parameter. 
This parameter is optional on both mappad and literal fields, and its 
default value is JUSTIFY NONE if JIBTIFY is not specified. 

Display Attribute Parameters 

The following eight parameters are used to describe the display 
characteristics of the field data vhen it is written to the specified 
device. If a device does not suppart a feature, such as reverse video 
or blink, the attribute is ignored. 

NOPROTBCT (or ENABLE) Parameter ; The NOPROTECT parameter, vhich is 
mutually exclusive with PROTECT, declares the associated field to be 
write-enabled upan display at the user terminal. When displayed on the 
line printer, the field is underlined (if underlining is available). 

PROTECT Parameter : The PROTECT parameter declares that the field is to 
be displayed write-protected v\hen written to the user terminal. When 
parinted at the line printer, it is not underlined (dispilayed normally) . 
If neither PROTECT nor NOPROTBCT is specified, PROTECT is assumed. 

BLINK Parameter ; The BLINK parameter defines the field to be blinked 
vhen displayed on the terminal. It has no effect in a device 
descriptor for the printer. 
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NOBLINK Parameter ; The NOBLINK parameter defines the field as not 
blinked v^en displayed at the user terminal. If both BLINK and NOBLINK 
are emitted, the default value is NOBLINK. 

REVERSE VIDEO Parameter ; The REVERSE VIDEO paraneter causes the field 
to be displayed in reverse video at the user terminal. It has no 
effect v^en output is printed at the line printer. 

NORMAL VIDEO Parameter ; “Ihe NORMAL VIDEO parameter declares the field 
to be displayed in normal video at the terminal. If both the REVERSE 
VIDEO and NORMAL VIDEO parameters are emitted, the default value is 
NCM1AL VIDEO. 

NODISPLAY (or HOLD) Parameter ; The NODISPLAY parameter causes the 
field not to be displayed v^^en the form is output. It is valid on all 
terminal and line printer device types. 

DISPIAY (or FREE) Parameter ; The DISPLAY attribute causes the field to 
be displayed v»iien the form is output to either the terminal or the line 
printer. If both the DISPLAY and NODISPIAY parameters are emitted, the 
default value is DISPLAY. 


FIELD DEFINITION EXAMPLES: FORMAT DESCRIPTOR 

The following FIX, coding example stows how the types of FCRMAT fields 
discussed in this section are defined. The lines of code also stow 
i^^ge of some field parameters discussed. Before each field 
definition, a comnent line has been inserted that identifies the type 
of field being defined. 

* MAPPED FIELD, NOT WRITE-PROrECTED 

* 

INVNIM FIELD POSITION (70,2), LENGTH 6, NO PROTECT 

* LITERAL FIELD 

* 

FIELD 'Literal String Ttest', POSITION (1,4) ; 


PROGRAMMING AIDS 

The following paragrajAis describe FIX statements to assist the 
programmer designing a form. They include a macro capability (the 
IXFINE statement) and iterative field generation (the REPEAT 
statement). 
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MACRO DEFINITION 

Currently, a macro consists simply of one text item replacing another 
item or text string (i.e., a synonym). 

name EEFINE item 


The DEFINE statement allows the definition of a macro. 

A DEFINE statement must be preceded by the name of the macro, starting 
in Column 1. The statement name must be tollowed by one or more spaces 
and then by the macro text. 

Whenever the macro name is encountered as a single item within an input 
line (not in a literal text string), the macro name is replaced by the 
given definition. All macros must be defined before they are used. 

Macro definitions are not retained between form definitions. They are 
erased after each EMD STREAM and END FORMAT statanent. 

Examples 


FLD 

DEbTNE 

FIELD 

LEN 

IXIFINE 

LENGTH 

POS 

DEFINE 

POSITIC»L 

DIX 

DEFINE 

5 

DIY 

* 

DEFINE 

10 


* 

* FIELD DEFINITIOSI USING ABOVE MACRO DEFINITIONS 
DATAl FLD, POS (D1X,D1Y) , LEN 10 

* 

* NOTE THAT THIS HAS THE SAME FUNCTIOI AS: 

DATAl FIELD, POSITION (5,10), LENGTH 10 


ITERATIVE FIELD GENERATIOJ 

Iterative field generation allows generation of multiple blocks of 
field statements with only one block definition. Fields to be 
generated in this manner must be enclosed within REPEAT and END REPEAT 
statements. 

Iterative field generation is permitted in both STREAM descriptor and 
FORMAT descriptor definitions. A two-digit iteration number is 
appended to any field name found in either the left margin or 
immediately tollowing a STREAM field statement. If the field name is 
seven or eight characters, it is truncated to six characters to permit 
the iteration number to be appended. The same is true for FORMAT 
(mapped) field names encountered in direct, output-literal, and 
input/empty-conditional STREAM descriptor fields. 
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► REffiAT n 

The REKIAT statement defines the beginning of an iterative field 
generation (REPEAT) block. It must be rollowed by an integer (n) 
greater than zero that represents the number of iterations to make 
trough the field definitions that follow in the FDL source text. The 
iteration counter is initially set to one and is incremented by one at 
each pass through the REPEAT block. When the counter exceeds the 
specified repeat count, the statement immediately following the 
associated END REPEAT statement is processed. 

Only FIELD statements are permitted within a REPEAT block. 

^ END REPEAT 

The END REPEAT statement terminates a REMIAT block. Ebr each REPEAT 
statement there must be a corresponding END REPEAT statement. Repeat 
blocks may not be nested. 


RELATIVE POSITION PARAMETER 

A second form of the POSITION parameter is available to fields defined 
within a repeat block. This permits the field coordinates to be 
relative to the current iteration number instead of absolute line and 
column. 

positionir^ is s^cified by placing a plus or minus sign 
immediately preceding the line and/or column definition in the POSITION 
parameter. The absolute line or column number is computed by addirq or 
subtracting the current iteration number to or tram the specified 
offset. 

An example of both iterative field generation and relative positioning 
is shown in the following iinew of FDL code: 

* THIS BLOCK WILL BE REPEATED 3 TIMES 

* 

REPEAT 3 

LASTNM FIELD LENCJTH 20, POSITION (10,+7) 

FRSTNM FIELD LENGTH 10, POSITION (35,+7) 

MIDDIN FIELD LENGTH 1, POSITION (50,+7) 

END REPEAT 
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The previously shown FDL code that used the relative position feature 
and a repeat block accomplishes the same function as the following FDL 
code that does not take advantage of these features: 


LASTWI01 

FIELD 

LENGTH 

20, 

POSITION 

(10,8) 

FRSTIM01 

FIELD 

LENGTH 

10, 

POSITICN 

(35,8) 

MIDDIN01 

FIELD 

LENGTH 

1, 

POSITION 

(50,8) 

LASTm02 

FIELD 

LENGTH 

20, 

POSITICN 

(10,9) 

FRSTM402 

FIELD 

LENGTH 

10, 

POSITION 

(35,9) 

MIDDIN02 

FIELD 

LENGTH 

1, 

POSITION 

(50,9) 

LAST^03 

FIELD 

LENGTH 

20, 

POSITION 

(10,10) 

FRSTm03 

FIELD 

LENGTH 

10, 

POSITION 

(35,10) 

MIDDIN03 

FIELD 

LENGTH 

1, 

POSITION 

(50,10) 


LISTING CONTROL STATEMENTS 
^ NOLIST 

The NOLIST statement disables the listing of all FDL statements, macro 
and repeat block expansions, except tor those containing errors. It is 
overridden only by the -EXPLIST command line option. 

^ EJECT 

The EJECT statement causes the listing to eject to the top of a new 
page v^en the listing file is output (spooled) to the line printer. 
The old page header is retained. Ebr a new page header, refer to the 
section entitled 'General Syntax'. The EJECT statement has no effect 
if the listing is turned off (via the ERRORS ONLY option or NOLIST 
statement). 


ALTERNATE INPUT FILE ($INSERT) 

► $INSERT pathname 

The contents of another FDL source file may be inserted into the 
primary input file at translation time. This is accomplished by 
placing the $INSERT directive in the left margin of the input line, 
followed by at least one space, and then the pathname of the file to be 
inserted. Input is then obtained from the inserted (alternate) disk 
file until the end of file (EOF) is encountered. When EOF is reached, 
FDL resumes processing the primary input file at the line following the 
$INSERT directive. No modification of the main input file is done. 
This temporarily "switches" the input flow from the primary to the 
alternate input file. 
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The $INSERT directive provides a convenient method of incorporating a 
corrmon macro definition file into an FDL source file. For example: 

$INSERT <SOF‘IWR> FORMS> MACROS 


FDL TRANSLATION, ClMMAND FORMAT 
► FDL pathname -options 

FDL is invoked by entering the external canmand FDL. Ihe command may 
be tollowed by an input file name and/or a list of translation options. 

pathname specifies the input (source) text if it is to be obtained from 
file specified by pathname . This parameter may only appear immediately 
following the command (in the option -INPLJT) name. 


Option 

Definition 

-INPirr pathname 

defines the source file, same as pathname, but 
may appear anyv\^iere on the ccximand line 

-INPITT TTY 

source text is to be obtained from the user 
terminal 

-LISTING 

listing file is to be generated 

-LISTING ipath 

listing is to be written to file specified by the 
pathname Ipath 

-LISTING NO 

no listing file is to be produced 

-LISTING TTY 

listing is to be printed at user terminal 

-LISTING SPOOL 

listing file is to be routed directly to spool 
queue - the name of the spool file is printed on 
the user terminal prior to start of translation 

-BINARY 

binary file is to be generated 

-BINARY bpath 

binary file output file is to be generated with 
the name specified by bpath 

-BINARY NO 

no binary file is to be generated 
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If a -BINARY or -LISTING option is not tollowed by a Ipath or opath , 
the binary file is written to either the file open on File Unit 3 or to 
a file called B_filenaine, if no file is open. Similarly, the listing 
file is written to either the file open on File Unit 2 or to a file 
called L_filename, if no file is open. 


The following 
underlined): 

option 

^OBJLIST 

^MACLIST 

-ERRL IST 

-EXPLIST 

-ERRT ERM 

-lOFLIST 

-REPLIST 


are the FDL-specific options (minimun abbreviations are 
definition 

list Quitted object text 
generate expanded macro listing 
generate errors-only listirg 
override NOLIST pseudo-op 
list errors on user terminal 
list I/O and device formats 
expand and list repeat blocks 


Each FDL-specific option except -EXPLIST may be preceded by a NO to 
reverse the option's meaning. For example, -NCMACLIST specifies that 
an expanded macro listing is to be suppressed. An optional parameter 
may be abbreviated to the minimun number of characters required to 
distinguish it from other parameters. For example: 


FDL FDEF15 -LISTING SPOOL H3INARY NO -CBJ -MAC 


Default Option Values 

Each installation may choose a set of default options for the FDL 
translator. Currently, the following options are standard: 

-LISTING BINARY -lOFLIST -ERRTERM 

All other options are disabled. FDL defaults are set by the A-register 
setting in the translator's monory-image file. The user may select his 
own default options by RESTORE'ing a copy of FDL and SAVE'ing it with 
the desired bits set in the A-register. The following table shows the 
A-register hit settings for FDL options and device codes: 
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options device codes 

bit set for 


1 -OBJLIST 

2 -MACLIST 

3 -ERRLIST 

4 -EXPLIST 

5 -ERRTERM 

6 -lOFLIST 

7 -REPLIST 
8-10 input device 

11-13 listing device 
14-16 binary device 

The default A-register setting is '6777. 


RUN-TIME MESSAGES 

After each stream or format descriptor is translated, FDL prints a 
message at the user terminal containing the nimber of errors 
encountered in the source text and the FDL revision number. 


FDL TEMPORARY FILES 

While translating a source file, the FDL translator may produce one or 
more of the following files: 

Name Format Contents 

ER##uu ascii error definitions (*) 

RPMuu ascii current repeat block 
IN#ltuu ascii input stream/substream definition 
OU#|fuu ascii/ output stream/substream format 
binary device format map 

All files are created and deleted by FDL. The only way that the user 
can examine them is to use CNTL-P to break out of the translator and/or 
perfonn a LISTF while another user is running FDL in the same UFD. 

* The in the filename denotes the current user number - this 
permits multiple FDL translations simultaneously within the same 
directory. 


0 > none 

1 > terminal 

2 > paper tape 

3 > card reader 

4 > printer 

5 > magtape 

6 > undefined 

7 > disk file 


REV. 0 


22 



PDR3040 


FORMS DEFINITION LANGUAGE 


FDL COMMAND LINE EXAMPLE 

OK, FIX DSl 
GO 

0000 ERRORS (FDL, REV 16 - 16-FEB-79) 
0000 ERRORS (FDL, REV 16 - 16-FEB-79) 

OK, 
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FORMS AEMINISTRATIVE mOCESSOR 
(FAP), 

REFERENCE INF(»MATION 


FUNCTION 

The FCKMS Administrative Processor (FAP) provides the commands to 
create and maintain the forms definition catalog, configure new 
terminals and new device drivers into the FORMS system, and obtain the 
system status. 

COMMAND FORMAT 

FAP is invoked by typing the command: FAP. FAP prints a header line 
followed by the current revision number. 

FAP COMMANDS 

The following paragraphs describe the commands supported by FAP. All 
ccmmai'id names may be abbreviated to three characters. 

Available FAP commands are: 

ADD 

CREATE 

GENERATE 

JOURNAL 

LINK 

LIST 

PURGE 

QUIT 

REPLACE 

TCB 


[LIST I 

► ADD filename LlIST UPDATESJ 

The ADD command enables the user to add form definitions to the FORMS 
catalog. The name of the binary form definition file ( filename) , 
generated by the FDL translator, must immediately follow the keyword 
ADD. This filename usually starts with B_. One binary file may 
contain more than one form definition (e.g., if there was one stream 
descriptor and one format descriptor with definitions tor three 
devices, the binary file contains four form definitions) . FAP 
ccnsiders each DEVICE descriptor defined under a single FOFMAT 
descriptor to be a separate form. 
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The AEO conraiand adds only new modules to the FORMS catalog. Any 
attempt to replace a torm already residing in the FOR'iS catalog with 
the AIX) command causes the new form definition to be ignored and a 
warning message to be printed at the user terminal. 

The input (binary) file name may be followed by the parameter LIST or 
LIST UPiATES. If this is specified, all torm definitions added to the 
FCKMS directory are listed by name on the terminal. 

When the binary file has been processed, the number of modules added 
and ignored (due to duplicate entries) is printed. 

If any translation errors were generated by FDL, the message WARNING!! 
form-name CCNTAINS ERRORS is printed or displayed at the terminal. A 
binary form definition with translation errors will probably generate 
undesirable results at run-time. The user must correct the source file 
and retranslate it with FDL. 

ADD Examples 

ADD B0FM03 
01 DEFINITION ADDED. 

ADD B^M04 LIST 


DEDUCT 

STR 


V00 

ADIED 

lEDUCT 

FMT 

VISTAR3 

V00 

ADIED 

DEDUCT 

FMT 

PRINTER 

V00 

ADDED 


03 DEFINITIONS ADDED. 
* 


^ CREATE [DIRECTORY] 

The CFiEATE (or CREATE DIRECTORY) command allows creation of a skeleton 
FORMS catalog. 

If the FCWIS directory does not exist, FAP requests a disk volume-id on 
vhich the UFD named FORMS* is to be created. The user must then enter 
the volume-id (DSKERAT name) of the pack/partition that will contain the 
FCH4S directory. FAP then asks tor the MFD owner password on this 
volume. After this information has been entered, the FCRMS UFD, 
catalog, and terminal configuraticai files are created. The CREATE 
command produces an error message if the FORMS catalog already exists. 
To create a tresh copy, the old file must first be deleted using the 
TREEEL command under FUTIL. 
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If the FORMS* UFD is created with FAP by the user, the following files 
must be copied to this directory before executing an application 
program that uses FORMS: 

DCF.AS RUN.ER DCF.BN 

These files may be found in the FCMIS* UFD as released on the master 
disk. 

CREATE Example 


The following is an example of CFIEATE command dialogue. 


OK, F^ 

GO 

FAP REV 16 11 - FEB - 79 

* CREATE 

UFD "FORMS*" DOES NOT EXIST 
SHALL I CREATE IT? YES 

ENTER OWNER PASSWORD (IT WON'T ECHO): ABCDEF 
THIS MFD IS FULL, TRY AGAIN. 

ENTER DISK VOLUME-ID: SOFTWR 

ENTER OWNER PASSWCMD (IT WON'T ECHO) XXXXXX 

TCB CREATED. 

DIRECTORY CREATED. 

* 


On any input request within the CREATE dialogue, the user may input 
CNTL-C to abort creation and return to tlie FAP coontnand level. 


^ GENERATE 

The GENERATE command is issued when the device control file has been 
modified; normally, v4ien a new device driver has been added to the 
system or a device driver has been removed. The GENERATE command 
creates three $INSERT files and one binary file in FOFMS* directory. 
The files generated are as follows: 
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. EEVEXT - external declaration statements for 
run-time device drivers 
. DEVDAC - 64R mode driver dispatch table 
. EEVIP - 64V mode driver dispatch table 
. DCF.BN - binary representation of the new device 
control file (ICF.AS) 


The GENERATE command mijst be issued and a new run-time I/O package must 
be assembled each time the device control file (DCF) is modified. 


► JOURNAL 


filename 

START ON filename 
STOP 


The JOURNAL command allov\^ the logging of transactions with the FCffMS 
catalog in an ASCII file that can be printed. All ADD, REPLACE, PURGE 
(described belov\4 r and TCB (described below) transactions are recorded 
in the JOURNAL file. 


The JDURI^L command may be used to enable or disable the loggirg 
function. To disable it, the command JOURNAL or JOURNAL STOP may be 
issued. To enable it, the command line JOURNAL filename or JOURNAL 
START ON <filename> may be issued. 

JOURtftL Example 

* JOURNAL LOG000 

* ADD BF01 

* 08 DESCRIPTIONS AIX)ED. 

* JOURmL STOP 

* 


► LINK 


ALL 

formname 


The LINK ccxrunand allows users to upgrade to current software revisions 
without having to rebuild each form definition. It may also be used to 
recover from various form definition file inconsistencies vAien a 
run-time error dictates such recovery is necessary. 


Ihere are two LINK command forms. LINK ALL specifies that all form 
definitions contained in the FORMS directory are to be re-linked. If 
the LINK command is followed by a formname, only the specified form 
definition is linked. 


Linking is the process that combines the STREAM and FORMAT descriptors 
into one form definition. This form definition is then stored in a 
file in the directory named FORMS>LNK.FD, for faster access at 
execution time. It is the linked form definition and not the 
individual stream and format descriptor that is used when a form is 
invoked at execution time (run-time). 
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Hie linked form definitions are transparent to the user. They are 
automatically created or updated by PAP when a form definition is added 
to or replaced in the catalog. The corresponding link file is deleted 
v\hen a format descriptor is purged. 


^ LIST [FILE filename] 


ON TERMINAL 
ON FILE filename 2 


The LIST command causes all or part of the FORMS catalog to be listed 
by name and type. This may be followed by a form name specifier to 
selectively list a part of the catalog. If the form name specifier is 
omitted, the entire catalog is listed. If the phrase ON FILE filename 
2 is included, the catalog listing is written to the specified file. 
If the phrase CN TERMINAL is specified, or if the ON FILE specifier is 
emitted, the listing is written to the user terminal. 


The information in the catalog listing includes: 

. formname, type, and device (if any) 

. version number 
. owner (login) name 

. creation, last access, last modified dates 
(file output only) 


LIST Example 
* LIST 

FORMS DIRECTORY ON THURSDAY, FEBRUARY 2, 1978 AT 9:45 PM 


NAME 

TYPE 

DEVICE 

VER 

OWNER 

HDRF01 

STR 


V02 

JIMW 

HE«F01 

FMT 

VISTAR3 

V00 

JIMW 

HDRF02 

S'PR 


V00 

DAVEW 

HDRF02 

FMT 

VISTAR3 

V00 

DAVEW 


04 ENTRIES. 

* 


^ PURG E (formname-specification) I[LIST UPDATES] 

The PURGE command purges form definitions from the FORMS catalog. The 
PURGE caonmand must be followed by a form name specification that 
designates v^ich form definitions are to be purged. It may also be 
followed by the word LIST or LIST UPDATES, v*iich causes all purged 
forms to be listed by name on the user terminal. 
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Ttie formname-specification designates the form definitions to vAiich the 
invocation of the EHJRGE command applies. Both PURGE and LIST commands 
use this option. 

Ihe formname-specification is enclosed in jarentheses and has the 
following formats: 

tormname 
formname.type 
tormname.type:device 

type may be t 

STR for stream descriptor, or 

FMT for format descriptor 

If only formname is specified, the PURGE command relates to all forms 
with the givon name, any type and any device. If the second 
specification is used, the command relates to all forms of the given 
name and type. If the type is EMT, it relates to all device 
descriptors within the format definition. If the third type of 
specification is used, the command relates to the one definition that 
contains the sane name, type, and device. This letter construction 
should only be used on format descriptors (there is no device 
definition tor a stream descriptor!). 

If any item in the form name specifier (formname, type, or device) is 
specified as an asterisk (*), or as the word ANY, no check will be made 
on that item vhen scanning the FCR4S catalog. 

Up to 20 tormnames may be specified within the parentheses, separated 
by commas. 

PURGE Examples 

OK, FAP 
GO 

FAP REV 16 23-FEB-79 


* PURGE (CRDER19) 

2 ENTRIES PURGED. 

* PURGE (a^raR20.STO) 

1 ENTRY PURGED. 

* PURGE (0RDER21. FMT: OWL1200) 

1 ENTRY PURGED. 
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► QUIT 

The QUIT canmand causes FAP to exit and return to Primos command level. 
FAP may be re-entered by typing the START (S) command. 

QUIT Exanple 

* QUIT 

OK, 


► REEtACE filename 


The REKACE command functions the same as the ADD command, but causes 
any form definiticxis in the FORMS catalog that are redefined in the 
input (binary) file filename to be replaced with the new definition. 
Any form definitions in the binary file that are not defined in the 
catalog are added. 

REPLACE Example 

* REPLACE B-F019 

02 DEFINITIONS REPLACED. 

* REPLACE B-^020 

01 DEFINITION ADDED 03 DEFINITIONS REPLACED. 


► 191 


uu terminal 
* terminal 
LIST filename 
LIST 


/ 


The TCB command modifies the terminal configuration file. This file 
contains a 64 by 4 word table that describes the terminal type for each 
FORMS user on the (local) computer system. It is used in conjunction 
with the device control file (DCF) at run-time to select the terminal 
device driver for a given FORMS user. Both TCB and DCF files are 
©{plained in detail in ^pendix B. 


Tb modify the terminal configuration file, the TCB canmand may 
optionally be followed by parameters that reflect the type of operation 
being performed. The parameter terminal specifies a type of terminal, 
such as CWL1200 or VISTAR3. The user nunber, im vhen specified 
initiates an addition, a replacement, or a deletion trcxn the Terminal 
Configuration file with regard to the user specified by ^.. When 
specified alone, uu causes the user with that number to be removed 
(deleted) from the block. If it is attempted to delete a nonexistant 
entry, a warning message and returns to FAP canmand level. If the 
value uu is not already in the terminal configuration file, and if 
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specified with a value for terminal , an addition is made to the file 
for user m with terminal type terminal . However, if an entry for uu 
already exists in the terminal configuration file, and if a value for 
terminal is also specified, then a new entry replaces the existing 
entry for in the file. The TCB command with the parameter * in 

place of ^ will cause the current values for to be placed in the 
terminal configuration file. TCB with the optional parameter LIST 
lists all the files in the FOPMS catalog (directory). TCB LIST 
filename lists only those entries that pertain to filename . lb add or 
change the terminal type, the 1- to 8- character terminal name must be 
input. If the specified user already had a TCB entry, the name of 
the old terminal type is printed on the terminal. 

* TCB LIST 

TERMINAL CCNFIGURATION ON TUESEAY, JANUARY 9, 1979 AT 11:58 AM 


USER 

TERMINAL 

03 

VISTAR3 

04 

CWL1200 

05 

CWL1200 

06 

GWL1200 

07 

OWL1200 

08 

GWL1200 

09 

OWL1200 

10 

CWL1200 

11 

OWL1200 

12 

CWL1200 


32 ENTRIES. 
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FAP EXAMPLE 

Having translated the example format and stream in Section 3 thus 
producing a binary file B_pATASl and a listing file L_pATASl, the 
binary representation may be placed in the catalog by using the FAP 
ccxtimand, as follovs: 

OK, FAP 
GO 

FAP REV 16 23-FEB-79 

* ADD B«DATAS1 

1 DEFINITION ADDED 

* LIST 

FORMS DIRECTCRY LISTING ON FRIDAY, FEBRUARY 23, 1979 AT 2:12 PM 


NAME 

TYIE 

device 

ver 

OWNER 

PHOmENU 

FMT 

aWL1200 

V08 

DCNL 

raONMENU 

STR 


V08 

DONL 

PHONFM 

FMT 

CIWL1200 

V08 

DCNL 

PHONEM 

STR 


V08 

DONL 

PHONFM 

FMT 

VISTAR3 

V00 

DOJL 

HiON^NU 

EMT 

VISTAR3 

V00 

DONL 

DATASl 

FMT 

OWL1200 

V00 

JDOAKS 

DATASl 

STR 


V00 

JDQAKS 

FINCER01 

STO 


VI8 

STEVE1 

fin:er01 

EMT 

OWL1200 

V18 

STEVE1 


11 ENTRIES. 
* QUIT 

OK, 
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SECTION 7 

EXAMPLE FCRTRAN PROGRAM 


INTRODUCTION 

Hiis section describes the development of a FO^S application program 
trcm source coding to loading and execution. It also describes how to 
prepare the data that defines the form and how to place that data in 
the FORMS catalog. The complete source listing tor the example is in 
^pendix E. 

This example is based on a practical use of FCRMS to keep track of 
customer orders, shipping information, and billable accounts. The 
program allows the user to input information at the terminal and store 
this information on a disk file. The application is typical of many 
parts distribution and billing operations. An example of the screen 
seen by the user is shown in Figure 7—1. Features that are essential 
to every FORMS afplication program as well as some special features 
unique to this application are discussed together with source code that 
illustrate these features. They are: 

• Setting up data areas through use of standard FORTRAN 
statements (i.e., LOGICAL, INTEGER, EQUIVALANCE) . 

• Extending terminal I/O buffer size with calls to the Primes 
subroutine ATTDEV. 

• Initializing control and output files (named ATS.C and ATS.D) 
with calls to the Primes subroutines SRCH$$ and PRWF$$. 

• Initializing the descriptor for the form to be used by means 
of a formatted READ statement that transfers the FORMS 
directive ##INVOKE to the terminal device driver and causes 
the form to be initialized at the terminal i.e., displayed on 
the terminal screen). 

• Readir^ the current control number from the control file, 
ATS.C, and updating the control file with the next control 
nunber. 

• Identifying, to FORMS, the substream that is to be accessed 
next. ##SuBSTREAM is used in this case since the data input 
and output are contained in more than one logical record. If 
there were only one record, then the STREAM statement WDuld 
be sufficient. When the header is written, the program sets 
up a substream tor handling errror messages ai^ two other 
Slipstreams; one for general name and address information, 
and one for parts list information. 


7 


1 


November 1979 



SECTION 7 


Pm3040 


FOPH PDrii77 m # 1 CODESIt ' 

I. PICKUP 

iifmia nBt€ [ 3 a. pppcel positiohi * 

PODREC.5 [" 3 3. OPS 

[ .3.4. riPST CLPSS 

I 3 5. SPEC OELI^ 

i 3 s. tfjck 

^ V: a. PPI ?mtl ' 

iMlIi- 3 j ®. PIP PPEICH" 

c : : feop m ■ " i- ■ ■ 

MSmil PE'iPCE'S-op's-:^* : i s.o: i i 

C3 f>P?CE i C 3 CCCESU 

ilLlftELt- . , ( 1 -COST F.O. i 'i e-:v;:'3 '4f..pPEFBIB 

^ .3 ::vv.y:^ i;,.C.Ci.O. 



Figure 7-1, Screen Display Produced by Running 
Exemple Program. 
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• Accepting input data fron the terminal using formatted READS 
and FORMS run-time directives. 

• Positioning the control file to the next control nunber to be 
read, and clearing the terminal screen of the last block of 
data written to the output file. 

• Exiting from the application program vhen done. 


WRITING THE PROGRAM 
Setting Lp Data Areas 

The following code illustrates how some of the data areas for the 
example program are defined. 

INTEGER NAMAI]R(75), VIA, HOW, REPL, INTO, BILL, SaJtM(4) , 

+ CHNNUM(4) , CP0(4), AC0THR(15), AIRSPR, INS (5) , 

+ TYPE, CODE, NWIO, ATSNliM, B, I, J, MCRE, FLD1(4,4), 

+ yESN0B(4), AC'IBUF(4,3) , FLD2(4,3) 


NAMAER, for example, is intended to acccxnodate up to 75 words (or 150 
ASCII characters) of name and address information. 


Extending Size of Terminal I/O Buffers 


The number of characters handled by a single transaction by this 
program (150) happens to be more than the default line size of the 
terminal read-write buffers (72). However, the size of the I/O 
terminal buffers may be changed by calls to the Primos subroutine 
ATTEEV. For example; 

C-EXTEND TERMINAL, FILE I/O BUFFERS. 

C 

CALL ATTDEV(1,1,0,150) 

CALL ATTK:V(6,7,2,150) 

The first call to ATTEEV sets up an input buffer, opjen for reading, 
tron the terminal on File Unit 1. The second call to ATTEEV sets up an 
output buffer, open for writing on File Unit 6. In both cases, the 
size of the Duffer is specified to be 150 characters. 


Shared Library Initialization 


In order to use the FORMS run-time directives with the shared 
libraries, the tollowing call must be present in the application 
program prior to the first SDINVOKE directive: 

CALL FORM$I 
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This requiranent is applicable to the 64V mode shared version of FCHMS 
and is ignored for 64R mode and non-shared 64V mode. 

Selecting a Library 

It is a system administration decision Whether or not to support the 
shared libraries. If shared FORMS is supported, shared COBOL, MIEAS, 
and FORTRAN must be supported as wall. If shared libraries are in use, 
the FOEMS shared library file is named VFOPMS. 

Initializing Control and Output Files 

Calls to standard FRIMOS file system subroutines open, and read the 
control file (ATS.C) and open and position the output file (ATS.D) tor 
writing. This is shown in the following code: 

C-OKIN FILES, INVOKE FORM ON TERMINAL. 

C 

CALL SRCH$$(K$CLOS,0,0,1,0,CODE) 

CALL SRCH$$ (K$CLOS, 0,0,2,0,COEE) 

C 

C-READ CONTROL FILE, ATS.C . 

CALL SRCH$$ (KSRDWR, 'ATS.C , 5, l,TYPE,CODE) 

C-CHECK FOR FILE READAfRITE ERRCRS> 

IF (CODE.NE.0) CALL ERRPR$ (K$NRTN,CODE,'ATS.C , 5,0,0) 

C-OKIN AND POSITiai DATR FILE, ATS.D . 

CALL SRCH$$ (K5RDWR,' ATS.D' , 5,2,TYPE,CODE) 

IF (CaDE.NE.0) CALL ERRPR$(K$NRTN,CODE,'ATS.D',5,0,0) 

C 

CALL ERWF$$(K$POSN-fK$PRER,2,LOC(0) ,0,10000000,NWIO,CO[E) 

The first two calls to the subroutine SRCH$$ close any files that might 
have been left open on File Iftiits 1 and 2 before the execution of the 
application prc^ram started. The third call to SRCH$$ opens the file 
ATS.C for reading and writing on File lAiit 1. The program makes 
provision tor a standard error return. The fourth call to SRCH$$ 
likewise opens the output data file ATS.D for reading and writing on 
File Unit 2. Then, the call to PFWF$$ positions the output file to the 
next record to be written. 

Initializing Form Descriptor 

Every FORMS ajplication program must identify the name of the form 
descriptor file installed in the F0R4S catalog. This is accomplished 
by an ##INVOP® run-time directive embedded in a formatted WRITE 
statanent. The keyword ##INVOKE has meaning to the FORMS subroutine 
package and FORMS user to set up a function call to the run-time 
directive ##INVOKE. The use of the ##INVDKE directive causes the form 
to be accessed in the FCRMS catalog and displayed at the terminal. 
Data can then be entered into the unprotected fields at the terminal. 
Use of the frfINVOKE directive is illustrated by the following code; 
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EX?VMPLE FCRTRAN FROGRM 


C-IIXNTIFY FORM FCR USE BY APPLiCATICN PROGRAM, 

C-AND WRITE FCRM AT TERMINAL. 

C 

WRITE (1,20) 

20 FORMAT {' ##INVOKE AEMNSTV ') 

This coding identifies the formname to be used as AEMN377. When 
executed, the code causes FORMS to search for AEMN377 in the fontis 
catalog, which is contained in a UFD named FORMS* . Then, FCRMS 
displays the form at the terminal as previously described. 

Reading and Resetting Opntrol Number 

This application program accesses a control file named ATS.C to assign 
a nun±)er to identify the itan to the data record currently being 
prepared at the terminal. The next sequential control number must also 
be assignel for later use in updating the control file. This is 
acccmplished by the following standard I/O calls and calculation: 

C-PROCEDURE TO ASSIGN NEXT ATS #. 

C 

C-POSITICW TO NEXT DATA RECCRD. 

C 

100 CALL PRWF$$(K$POSN-«<$PREA,1,LOC(0) ,0,000000,NWIO,CODE) 

C-READ ATS.C TO GET ATSNUM 

C 

READ (5,120,ERR=160,END=160) ATSNLM 
120 FORMAT(16) 

GO TO 200 
C 

C-HERE ON E(F, ETC. 

C 

160 ATSNm=0 

n 

C-ASSIGN NEXT SEQUENTIAL ATS #. 

180 ATSNUM=ATSNUM+1 

Using Substreams 


Figure 7-2 shows how a STREAM (i.e., the data record) typically may be 
subdivided into SlBSTREAMs (i.e., logical records). 

The use of substreams is not only a means for setting up logical 
records within the data record. Normally, FORMS expects the input and 
output data record(s) to be only one line of information. Substreams 
provide a way that the user may specify data records greater than 
normally expected. Substreams each may contain up to a line's worth of 
characters. As an aggregate, suDstreams make up a data record 
(STREAM) . This program demonstrates the use of si±)streams with FORMS. 
When the user desires to lexically separate data into several records, 
FCPMS substreams are used. Each substream is transferred as an 
individual data record when the application program is performing I/O 
operations. For example, it is desirable to output any error messages 
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Figure 7-2. SUBSTREAMS Within Data STREAM. 
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EXAMPLE FORTRAN PROGRAM 


in a separate substream (record). In the sample program, this is done 
by: 

C - WRITE ATS#, CLEAR \ARIABLE DATA, ERRCR MESSAGE. 

C 

200 WRITE (1,210) ATSNtM 

HCROUr=. FALSE. /*HEAEER NOT OUTPUT TO DISK FILE 

C-WRITE HEAIXR AND ERROR MESSAGE FIELD TOEN 

C UNPROTECTED DATA FIELDS, 

C-USING FORMS ##SUBSTREAM AND ##CLEAR DIRECTIVES. 

C 

210 FC«MAT('##SUBSTREAM HEAIER'A6/'##CLEAR'/'##SUBSTREAM ERROR'/") 

Statanent 210 writes the HEAOER and ERROR substreams to the tenninal. 
It also writes the control number and clears the unprotected (variable) 
data areas on the tenninal screen. 

Entering Data from the Terminal 

The following lines of code read the various data items after the user 
has entered them into the appropriate fields displayed at the terminal 
and has pressed the "ENTER" key. Some of the accompanying validation 
data is shovai. For example, if a blank name and address (NAMAER) is 
entered, the program branches to code that updates the control file, 
clears the screen, and exits. (See "exiting" later in this section.) 
FORMS directives are not used during this phase of program operation. 

C-READ IN NMES, AD^ESSES, AND ACCOUNTING INFC^MATION. 

C 

220 READ (1,240) NAMAER, VIA, HOW, REPL, INTC, BILL, SCNUM, 

+ CHGNUM, CPO, ACOTHR, AIRSPR, INS 

C 

IF (NAMAER(1).EQ.' ') GO TO 5000 /* BLANK NAME => EXIT 

C-READ NAMADR. NOTE 75 WORDS = 150 CHARACTERS, ALSO 

C-READ ACCOUNTING INFO (VARIABLES SXH AS: VIA, HOW, ETC.) 

240 FORMAT(75A2,2I1,3A1,12A2,15A2,A1,4A2,A1) 

Writing Data to the Output File 

The file header and account header are written to the disk file, 
followed by individual data items. Standard FORTRAN I/O is used as 
follows: 
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C - WRITE EATA TO DISK FILE. 

C 

DO 550 1=1,4 

IF {DESCR(1,I) .EQ.' ') GO TO 550 /* IGNCRE BLANK LINE 

IF (HOROUT) GO TO 540 
C 

C-WRITE ACCOUNT HEAIKR TO DISK FILE. 

C 

WRITE (6,525) ATSNIM, NAMAER, VIA, HOW, REH., INTO, BILL, SCNUM, 
+ CHGNUM, CPO, ACOTHR, AIRSPR, INS 

525 FORMAT ('*ATS',16/5 (15A2/) ,2I1,3A1,12A2A5A2/A1,4A2,A1) 

C 

Hmour=.TRUE. 

C 

C-WRITE INDIVIDUAL ITEM LINE TO DISK FILE. 

C 

540 WRITE (6,545) (PART(J,I) ,J=1,8), (DESCR(J,I) ,J=1,15) , 

+ (SN (J,I) ,J=1,4) , giY (I) , RTO (I) 

545 F0RMAT(7A2,A1,15A2,4A2,I4,A1) 

C 

550 CONTINUE 
Data Checking 


Ilie application program checks if there are any more items to be 
written, by checking tor nonzero data in the MORE field displayed at 
the terminal. If the user has entered data other than zero in the MORE 
field, it indicates that more information with respect to part nunbers 
etc is to be associated with the current order. Data items are written 
usirg the ##SLBSTREAM directive. This is shown in the following code, 
along with the test for "more" data. As each data item is entered from 
the terminal and written to the terminal, the terminal cursor is 
positioned the the next field to be read or written through use of the 
##POBITION directive. For example, see statement 580 of the following 
code. 

C-CHECK FOR MORE ITEM LINES. 

C 

C-IF NO MORE ITEMS, THEN EXIT. 

C 

IF (MORE.EQ.' ' .CR.MORE.EQ.'N'.O^.MCBE.EQ.'n') GO TO 180 

C-USE FORMS ##SUBSTREAM AND ##POSITION DIRECTIVES TO 

C - WRITE OUTPUT DATA RECORD. 

C 

C-DAIA ITEMS HAVE BEEN ENTERED AT THE TERMINAL BY USER. 

C 

C 

WRITE (1,580) 

580 FORMAT('jf#SUBSTREAM ITEMS'/' '/'##SUBSTREAM ITEMS'/ 

+ '# #P0SITI0N PART01') 

GO TO 400 /* NEXT SET OF ITEM LINES 
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Response to Data Input Errors 

Checks are made that the proper range or type of data values are 
entered by the user at the terminal. If a data input error occurs, the 
program usually branches to one of a nunber of internal routines that 
print and error message in the error substream and position the 
terminal cursor back to receive a correct value for the data itan that 
was in error. These routines uniformly anploy the ##SUBSTREAM 
directive to print the message at the terminal and the JSPOSITION 
directive to reposition the cursor. This is illustrated by the 
following typical lines of code: 

C-INCORRECT DATA IN AOCOUMTING FIELDS. 

C 

C ACTION TAKEN ON INOCRRECT 'VIA' CODE: 

C 

1000 WRITE (1,1010) 

1010 FORMAT ('»SUBSTREAM ERROR'/ 

+ 'via code must be 1-9'/ 

+ 'S#POSITION SHIPVIA') 

GO TO 220 
C 

C-ACTION TAKEN ON INCORRECT 'HOW' C(»E: 

C 

1020 WRITE (1,1030) 

1030 FORMAT('##SUBSTREAM ERROR'/ 

+ 'how code must be 1-4'/ 

+ ' ##posrnoN sHiPHow') 

GO TO 220 
C 

C - YES/NO ANSWER REQUIRED. 

C 

1040 WRITE (1,1050) (FLD1(J,I), J=l,4) 

1050 FORMAT('##SUBSTREAM ERR(»'/ 

+ 'yes/no (Y or N) response required'/ 

+ 'jt#POSITION ',4A2) 

GO TO 220 
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Exiting 


The exit code i;pdates the control file, closes the control file and 
output file, clears the terminal, and exits to FRIMOS. The exiting 
code is initiated vAien the program encounters a N^MAER field that is 
blank vtiich will occur v^en the user enters a blank in the NAMAIH 
field. The test statement for a NAMAER of blank as well as the exit 
code statements are shown in the following excerpts trcm the 
application program. 

C-HERE TO EXIT. UPDATE ATS # IN CONTROL FILE. 

C 

5000 CALL FRWF$$(K$POSN+K$PREA,1,LOC(0) ,0,000000,NWIO, CODE) 

C-WRITE ATSNUM IN ATS.C . 

WRITE(5,120) ATSNUM 

CALL FRWF$$(K$TRNO,1,LOC(0) ,0,000000,NWIO,C(J)E) 

C 

C-CLOSE CONTROL FILE AND DATA FILE. 

CALL SRCH$$ (K$CLOS,0,0,1,0,CODE) 

CALL SRCH$$(K$CLOS, 0,0,2,0,CODE) 

C 

c -USE FORM fjfCLEAR DIRECTIVE TO CLEAR TERMINAL DATA FIELDS, AND 

C-RELEASE SCREEN AND RETURN IT FOR USE BY FRIMOS. 

C 

WRITE (1,5020) 

5020 FORMAT('##CLEAR ALL'/'fr#RELEASE') 

C 

CALL EXIT 
END 
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CREATING THE FOPM DESCRIPTOR FILE 

The foregoing example discussed how the example application program v^s 
coded and reasons for using the various coding techniques. In 
addition, the user must be concerned with describing the form to be 
used with the program. The data contained with the fonn, both on the 
terminal screen and in the data record must be described using the FDL 
translator and placed on the FORMS catalog using the FAP ccxrenand (see 
Section 6). The form descriptor specified by the user.as a template 
that describes both how the form is to be displayed at the terminal and 
how it is to be stored, in terms of: the attributes of the data itans 
and the overall arrangement of the form. 

As stated in Sections 3 and 5, the FDL forms descriptor language is 
available to make a source language description of v\iiat the form looks 
like both on the terminal and in the data record. The syntax of FDL is 
summarized in Section 3 and described in Section 5. The following 
paragraphs discuss how the form used by the sample application prog ran 
is coded and translated. A complete listing of the sample form 
description is given in Appendix F. Features that are essential in 
every form description as well as some special features are discussed 
in this section together with some excerpts of the FDL source code. 
Features discussed in seme detail are: 

• setting up the FCRMS descriptors 

• defining the terminal devices used 

• initializing the data record and terminal screen display 

• defining data areas (fields) 

• differentiating input data from output data 

• differentiating literal data and variable data 

• using substreams 

• using the macro definition capability of FDL 

• specifying listing details 

The discussion is completed by a brief description of how to use the 
FDL language translator ccxnmand and how the FDL checks for errors in 
the source language input. This is followed by a discussion of how to 
install a form description in the FORMS catalog using FAP. 

Setting a Form Description 

Every form description consists of two parts: one to describe the data 
record, and the other to describe the form itself. These are the 
STREAM and the FORMAT descriptors respectively. The STREAM descriptor 
is bounded (defined) by a STREAM statement and an END STREAM statanent. 
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Likewise, a FORMAT descriptor is bounded by a FORMAT and END FCRMAT 
statement. In each form description, there need be only one STREM 
descriptor, since the internal data record need be only described once, 
fbwever, there must be one FORMAT descriptor tor each type of device 
the user wishes to use with the application program. An example of FDL 
code is given in the following paragraj^s. 

Defining Device Types 

For each terminal connected to the system that interfaces with the 
application program, there must be a DEVICE descriptor. These 
descriptors are bounded by DEVICE and END DEVICE and contained within 
the body of the FORMAT descriptor, as illustrated in the following FDL 
coding; 

ADMN377 STREAM 

• • • 

END STREAM 
ADMN377 FORMAT 

lEVECE OWL1200 

• • • 

END DEVICE 
DEVICE VISTAR3 

• • • 

END DEVICE 
END FORMAT 

Using SUBSTREAMS 


The discussion on the application program ^owed lx)W the program took 
advantage of the ##SUBSTREAM directive and the suDstream concept of 
FORMS to effectively use logical records. Within FDL, SUBSTREAM and 
END SUBSTREAM statements allow a user to define and delimit substreams. 
The substreams are set up in the STREAM descriptor. The data items 
(FIELDS) with a SUBSTREAM are mapped to fields in the FORMAT 
descriptor. In the example FDL coding, the substreams that have been 
set up correspond to the substreams that are handled by the program, 
i.e., there are: a header substream, a general substream, a data item 
substream, and an error substream. The following code excerpt shows 
how one of the substreams is defined; 

ADMN377 STREAM 
HEAIER SUBSTREAM 

FIELD (FCEMEftME,FCRMM\ME) 

FIELD ATSNUM, LENGTH 6, JUSTIFY RIGHT, ZERO-FILL, OUTPUT 
END SUBSTREAM 

* 

* 


END STREAM 

The following code in the FORMAT descriptor is the mapped equivalent of 
the sample SUBSTREAM: 
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* -HEADER LINE INFORMATION; 

* 

FIELD 'FORM' POSITION (2,1) 

FORMNAME FIELD LENGTH 8, POSITION (7,1) 

FIELD 'ATS #' POSmCW (20,1) 

ATSNUM FIELD LENGTH 6, POSITION (26,1) 

* 

Setting Data Areas (FIELDS) 

Data items are described by FIELD statements. FIELD statements may 
describe a literal, some system wide information, or may describe a 
variable. FIELD statements that describe a literal consist of the 
keyword FIELD and the literal in single quotes, tor example; 

FIELD 'CUSTOMER NAME' 

Fields that give system information such as time and date are described 
in Section 5. FIELD statements that describe variable (NOPROTECT) data 
items give the length of the field and some of the attributes of the 
data within the field, such as type, justification, validation, etc. 
There are differences between the format of a FIELD statement in a 
STREAM descriptor and a FIELD statement in a FORMAT descriptor. For 
example, the field name in a STREAM-FIELD statement is contained within 
the body of the statement following the keyword STREAM, and the field 
name of a FORMAT descriptor must appear in Column 1. However, there is 
a one-for-one mapping between the variable fields in a STREAM 
descriptor and the corresponding fields in the associated FORMAT 
descriptor. All of these practices are illustrated in the following 
code; 
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ADMN377 STREAM 

• • • 

* -SHIP TO NAME AND AIX^ESS. 

* 

NAMAER SUBSTREAM 

FIELD NAME, UINGTH 30, VALIDATE 'P' OR 'B' 
REPEAT 3 

FIELD AODR, LENGTH 30 
END REPEAT 

* 

FIELD ATTN, LENGTH 30 
END SUBSTREAM 


AEMN377 FORMAT 

• • • 

*-SHIP TO INFORMATION; 

4c 

FIELD 'SHIP TO ' POSITION (2,3), RVIDEO 
FIELD 'NAME' POSITION (12,3) 

NAME FIELD LEN 30, POSITION (24,3), NOPROTECT 

FIELD 'ADDRESS' POSITION (12,4) 

REPEAT 3 

ADDR FIELD LEN 30, POSITION (24,+3) , NOPROTECT 

END REPEAT 

FIELD 'ATTENTION' POSITION (12,7) 

ATTN FIELD LEN 30 POSITION (24,7) NOFROTECT 


Input and Output Data 


The listing generated by FCL separates the STREAM description into two 
areas, one showi^ INPUT field data and one showing OUTPUT field data. 
Refer to the listing in Appendix F. If the user does not specify 
otherwise, all fields are both INPUT/OUTPUT. An example of an output 
field is illustrated by the following line of code; 

FIELD ATSNUM, LENGTH 6, JUSTIFY RIGHT, ZERO-FILL, OUTPUT 

The listing in Appendix F shows how FDL separates INPUT and OUTPUT 
fields. A check of this listing will reveal that the field ATSNUM is 
present in the output description but not the input description. 

The variable (ATSNUM) is not specified at the terminal by the user, it 
is generated and used internally by the program. 

Literal and Variable Data 


Literal fields within a FORMAT are simply specified by the FIELD 
statement containing the literal string. For example; 

FIELD 'FORM' POSITION (2,1) 
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Variable fields may be specified by using the NOFROTECT attribute. For 
example: 

NAME FIELD LENGTH 30, POSITIOJ (24,3), NOPROTBCT 

FROTECTed fields may not be written into by the user. A NOPROTECTed 
field may be written into by the user. Fbr example: 

ATSNUM FIELD LENGTH 6, POSITIOL (26,1) , PROTECT 

using the Macro Definitions 


To show the flexibility and convenience of coding in FDL, the LXFINE 
statement is used in the sample codirg to make up a series of macro 
definitions that allow abbreviation of key words or often used names. 
These definitions are: 


* MACRO DEFINITIONS FCR FORMS DEFINITION LANGUAGE TRANSLATOR 

* COPYRIGHT 1979, PRIME CCMPUTER, FRAMINGHAM MA 

* 

F DEF FIELD 

V DEF VALILATE 

LEN L^F LENGTH 

POS DEF POSITION 

IN EEF INPUT 

OUT DEF OUTPUT 

JUS IXF JUSTIFY 

R DEF RIGHT 

L DEF LEFT 

C DEF CENTER 

NP EEF NOPROTECT 

RV DEF REVERSE VIIEO 

BL lEF BLINK 

* 

*-END FCRMS>MACROS 


Heretofore, example FEE code in this section were all spelled out. 
However, as Appendix F shows, the user may to take advantage of the 
abbreviation macros. For example consider the line: 

F NAME, LEN 30, V 'P' OR 'B' 

as opposed to; 

FIELD NAME, LENGTH 30, VALIDATE 'P' OR 'B' 

This saves time in typing input vhen often-used words such as VALIDATE 
are abbreviated to one letter (i.e., V). 
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CAUTION 

Using attoreviations makes it difficult or impossible to 
maintain the application program and its associated form 
descriptors. 

Macros may be written in-line — in the FIX code as shown here or may 
be inserted by the FDL statement $INSERT. The depth of a macro 
definition is internal to the descriptor that contains it. Thus, in 
the example FDL listing in ^pendix F, the macro definition statements 
in the STREiAM are in-line. In the FORMAT, the same macro definitions 
are referenced by a $INSERT statement. 

^)ecifying FDL Listing details 

FDL produces an output listing inless the user specifies otherwise. 
The user can control listing features with control statements such as 
$LIST and $NOLIST. One advantage of the listing is that the user can 
check and be sure his data item in the STREAM portion of the 
description map properly to the corresponding data item the FORMAT 
portion. For example; 

* -ITEM INFORMATION. 

* 

REffiAT 4 

FIELD PART, LENGTH 15, JUSTIFY RIGHT, SPACE-FILL 

FIELD IXSCR, LENGTH 30, JUSTIFY LEFT 

FIELD SN, LENGTH 8, JUSTIFY RIGHT, ZERO^ILL 

FIELD QTY, LENGTH 4, JUSTIFY RIGHT, ZERO^ILL, VALIDATE '9' CR 'B* 
FIELD RTN, LENGTH 1, VALIDATE 'A' OR 'B' 

END REPEAT 

in the SUBSTREAM fields correspond (i.e., map) to the following items 
in the FORMAT fields; 

REKIAT 4 

PART FIELD LENGTH 15, POSTTIOJ (2,+18), NOPROTBCT 

DESCR FIELD LENGTH 30, POSITION (19,+18) , NOPROTECT 

SN FIELD LENGTH 8, POSITION (51,+18), NOPROTBCT 

QTY FIELD LENGTH 4, POSITION (61,+18), NOPROTBCT 

RTN FIELD LENGTH 1, POSITIC*^ (67,+18) , NOPROTBCT 

END REPEAT 

Repeated Text 


The code in the previous example shows the use of the REPEAT feature in 
FDL viiiich allows a user to specify the duplication of similar fields 
over several lines on the teminal screen. In this case, the item 
"PARTS" was repeated four times using REPEAT 4. The END REPEAT 
statemait delimits the dcxnain of a REPEAT. 
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Listing Features 

Finally, the FDL output listing shows some additional useful 
information about the form descriptor. First, as shown in Appendix F, 
the items defined in the input strean and the output stream are listed 
in a separate cross-index after the listing of the translated STREAM 
code. For example, the header substream is OUTPUT but not INPUT 
information. Second, the listing provides a convenient chart of lines 
and columns for each DEVICE specified in the FORMAT descriptor (See 
Appendix F and Appendix H). For example, the last tvo pages of the 
listing in ^pendix F of the output listing (named AEMN377) show the 
fields in their relative position location, show literal fields as they 
appear, and show the location of the variable (NOFROTBCTed) fields by 
the lines of dashes. Refer to the listing in Appendix F for further 
information. 
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COMPILING THE APPLICATION PROGRAM 

Ihe example program is compiled using the FTN caimand as follows; 


OK, PIN MAIN -64V -LIST 
GO 

0000 ERRORS [<.MAIN.>FTOHREY15.3] 

OK, 

TRAIBLATING THE FDL SOURCE 

The source description of the form must be input to the FDL translator, 
using the FDL command. The translation produces an output file in a 
binary form vhich may be placed in the FORMS catalog. Files listed in 
the FORMS catalog can be read and interpreted by the application 
program at run-time. The following is an example of the FDL 
translation for the sample form descriptor named ADMN377. 

OK, FDL AEMN377 
GO 

0000 ERRORS (FDL, REV 16 - 16-FEB-79) 

0000 ERRORS (FDL, REV 16 - 16-FEB-79) 

OK, 

INSTALLING FORM raSCRIPTOR IN FCRMS CATALOG 

The FAP co«imand is used to install forms descriptors in the FORMS 
catalog and otherwise maintain this library. The following is a sample 
installation of the form descriptor AnMN377 in the FORMS catalog: 

OK, FAP 
GO 

FAP REV 16 2 3-DEC-78 

* ADD B ADMN377 

3 DEFINITIONS ADEED 

* QUIT 

OK, 

LOADING THE APPLICATION PROGRAM 

Since the sample program is compiled in V-mode the SEG loader must be 
used, and the appropriate V-mode libraries must be invoked. This 
procedure is illustrated in the following example: 
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OK, SBG 
GO 

# LCAD 

SAVE FILE TREE NAME: #MAIN 
$ LO BJVIAIN 
$ LIB VFORMS 
$ LIB V5P00$ 

s m 

LOAD CCMPLETE 
$ SAVE 
$ QUIT 

OK, 


RUNNING THE PROGRAM 

The program may be run by a simple invocation of the SEG command, 
follows: 

SEG #MAIN 


as 
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SECTION 8 

EXAMPLE COBOL PROGRAM 


INTRCDUCTION 

This section describes the development of a FORMS application program 
from source codirg to loading and execution. One of the significant 
differences between the program described in this section and the one 
described in Section 1, besides its being written in COBOL, is the fact 
that the program uses keyed-index files and interfaces with MIDAS as 
well as with FORMS. This section also describes the data used with the 
application program that defines the form and describes how to place 
the form descriptor in the FORMS catalog. 

The exanple program (named EEMOl) accepts a simple list of orders, 
typed at the terminal, and writes the items on the order list to a 
keyed-index file (named DBl). The data in the form is handled as a 
simple STREAM (i.e., only one logical record). An example of the 
screen, observed by the user, is shown in Figure 8-1. Features that 
are essential to every FORMS application program, as well as some 
special features unique to the ajplication are discussed with source 
code excerpts. Features discussed in this section are; 


• Defining files. 

• Settirg up data areas through use of standard COBOL statements. 

• Defining data screen. 

• Initializing the descriptor for the form to be used to means of a 
COBOL read statement that transfers the FORMS directive ##INVDKE 
to the tenninal device driver and causes the form to be displayed 
on the terminal screen. 

• V\ft:iting the header and other data to the terminal using FORMS 
directives. 

• Accepting input data from the tenninal using READ and FORMS 
run-time directives. 

• PDsitioning the tenninal cursor to the home position and clearing 
the terminal screen of the last block of data written. 

• Error handling by the application progran. 
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Figure 8-1. Screen Display Prodtced by Running Example Program. 
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• Exiting from the application program. 

WRITING THE PROGRAM 

A complete listing of the program's source coding appears in Appendix 

G. 

Defining Files 

The files to be used are defined with a standard COBOL programming 
practice, i.e., by the FILE CONTROL SECTION as follows; 

FILE-CONTROL. 

SELECT INFILE ASSIGN TO TERMINAL. 

SELECT ORDER-FILE ASSIGN TO PBMS 
ORGANIZATION IS INFIXED 
ACCESS IS DYNAMIC 
RECORD KEY IS ORDER-^EY 

ALTERNATE RECORD KEY IS 0RESR^^1AME WITH DUPLICATES 
ALTERmTE RECORD KEY IS STOCK-NO WITH DUPLICATES 
ALTERNATE RECORD KEY IS STOCKHDEL WITH DUPLICATES. 

Setting-l^ Data Areas 


The example program sets up the data areas, first, by defining the 
input and output data records in the FILE SECTION of the DATA DIVISION. 
This is shown in the following code: 
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DATA DIVISION. 

FILE SECTION. 

FD INFILE LABEL RECCRDG ARE OMITTED. 

01 SCR. 

02 FILLER PIC X{104). 

FD CRDER-FIEE LABEL RECORDS ARE STANDARD 
VALUE OF FILE-ID IS "CHEERS". 
01 ORDER-RBCCBD. 

02 ORIER-KEY. 

03 0REER-4I0 PIC 9(5). 

03 ORDER-ITEM PIC 99. 


02 ORKIR-^JAME 

PIC 

X(20). 

02 CRDER-AOOl 

PIC 

X(20) . 

02 0RIER-^E»2 

PIC 

X(20) . 

02 0RDER-Ar»3 

PIC 

X(20) . 

02 STOCK-NO 

PIC 

X(6). 

02 STOCK-DEL 

PIC 

X(8) . 

02 STOCK-QTY 
ORDERC. 

PIC 

S9(5) SIGN TRAILING SEPARATE 

02 FILLER 

PIC 

X(7). 

02 NEXT-CREER 

PIC 

9(b) . 

02 FILLER 

PIC 

X(94). 


Extending Size of Terminal I/O Buffers 

The number of characters handled by a single transaction by this 
program (150) happens to be more than the default line size of the 
terminal read-write buffers (72). Ifcwever, the size of the I/O 
terminal buffers may be changed by calls to the Primes subroutine 
ATTEEV. For example; 

* EXTEND TERMINAL, FILE I/O BUFFERS. 

* 

MOVE 0 TO VAR0. 

MOVE 1 TO VARl. 

MOVE 2 TO VAR2. 

MOVE 6 TO VAR6. 

MOVE 7 TO VAR7. 

MOVE 150 TO VAR150. 

CALL 'ATTDEV USING VARl, VARl, VAR0, VAR150. 

CALL 'ATTDEV' USING VAR6, VAR7, VAR2, VAR150. 

The first call to ATTEEV sets up an input buffer, opjen for readir^, 
tron the terminal on File Unit 1. The second call to ATTEEV sets up an 
output buffer, open for writing on File Unit 6. In both cases, the 
size of the buffer is sp)ecified to be 150 characters. 
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Shared Library Initialization 

In order to use the FORMS rixi-time directives with the shared 
libraries, the tollowing call must be present in the application 
program prior to the first ##INVOKE directive: 

CALL 'FOFM$I'. 

This requirenent is applicable to the 64V mode shared version of FORMS 
and is ignored for 64R mode and non-shared 64V mode. 

Selecting a Library 

It is a system administration decision vihether or not to support the 
shared libraries. If shared FORMS is supported, shared COBOL, MIDAS, 
and FORTRAN must be supported as well. If shared libraries are in use, 
the FORMS shared library file is named VFORMS. 


Defining FORMS Directives 


FORM directives used by the application program are defined in the 
WORKING STCmGE SECTION of the DMA DIVISION. This is one of the areas 
in vAiich the sample program differs from an "ordinary" COBOL program. 
The definition of the FORM directives to be used appears as follows: 

WORKING-STORAGE SECTION. 

* DEFINITION OF FORMS DIRECTIVES 

77 INV-C PIC X(12) VALUE '##INVDKE DSl'. 

77 REL-C PIC X (09) VALUE '##RELEASE'. 

77 PROT-C PIC X(25) VALUE '##PROTECT NAM ADI AD2 ADS'. 

77 ENAB-C PIC X(24) VALUE '##ENABLE NAM ADI AD2 ADS'. 

77 CLEAR-C PIC X(07) VALUE '##CLEAR'. 

77 CLA-C PIC X (11) VALUE ' ##CLEAR ALL'. 

* CURRENT ORDER 

77 CURR-ORD PIC 9 (5) . 

Defining Terminal Screen 

Also in the WORKING STORACE SECTION, the program defines the individual 
data items that appear on the terminal screen (DATA-SCREEN) , as 

follows: 
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01 DATA^CREEN. 

* CUSTCMER AND C3RDER 


INFORMATION 


02 

DSHMAM. 



03 CUSIND 

PIC XX. 


03 FILLER 

PIC X(18) 

02 

DS-ADl 

PIC X(20). 

02 

E6-AD2 

PIC X (20) . 

02 

DS^D3 

PIC X(20). 

02 

D6-STK. 



03 STK-ID 

PIC XX. 


03 FILLER 

PIC X (4) . 

02 

DS-QTY 

PIC 9(5). 

02 

D6-EATE 

PIC X(8) . 

02 

DS-ORDER 

PIC 9(5). 


The items defined as part of the form will be moved to the order record 
defined previously in the FILE SECTICW. 

Opening Files 


One of the first steps in the procedure is to open the input and output 
files, as shown by the following; 

mOCEDURE DIVISICW. 

START-iOINT. 

OPEN I-O ORKIRHEILE. 

OPEN I-O INFILE. 

Invoking Form 


INV-C has been defined as the FORMS ##INVDKE directive, thus 
WRITE SCR FROM INV-C 
causes the form to be displayed. 

Readirq and Checking Input 

After the data is entered at the terminal by the user, the program 
reads this data by the following code: 

B^INT. 

READ INFILE INTO DATA-SCREEN. 

IF CUSIND EQUAL '**' GO TO END-IT. 

If the user has input a double asterisk (**) for the variable (USIND, 
then the program exits to ERIMOS conmand level. 
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Writing Data 


The following code writes any existing data to the output file and 
returns, ready to receive additional input tron the user terminal: 

TRY-IT. 

MOVE ZEROES TO ORDER-^(EY. 

READ CRDER-FIIE KEY IS CRDER-KEY INVALID KEY 
GO TO TRY-IT. 

AID 1 TO NEXr-CRDER. 

MOVE NEXT-OREDR TO CURR-ORD. 

REWRITE CRDER-RBCORD. 

* 

MOVE DS-NAM TO OREER-^^AME. 

MOVE DS-ADl TO CRDER-ADDl. 

MOVE DS-AD2 TO 0RmR-ADD2. 

MOVE DG-AD3 TO 0RDER-ArD3. 

MOVE ZERO TO ORDER-ITEM. 

A-POINT. 

MOVE DS-STK TO STOCKH^O. 

INSPECT DS-STK REPLACING LEADING SPACES BY ZEROES. 

MOVE DS-UTY to STOCK-QTY. 

MOVE DS-DATE TO STOCK-DEL. 

* 

ADD 1 TO ORIDR-ITEM. 

MOVE CURR-ORD TO ORDER-NO. 

MOVE CURR-ORD TO DS-ORmR. 

* 

WRITE ORIER^^ECCRD. 

WRITE SCR FROM PROT-C. 

MOVE SPACES TO DS-STK, DB-QTY, ES-DATE. 

WRITE SCR FROM DATA-SCREEN. 

READ INFILE INTO EATA-^CREEN. 

IF STK-ID NOT EQUAL '**' GO TO A-tOINT. 

* 

WRITE SCR FROM ENAB-C. 

WRITE SCR FROM CLEAR-C. 

GO TO B-POINT. 
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Exiting 


FORMS directives exist to clear and release the terminal screen. They 
are called v^en the program exits, by invoicing the working storage 
variables CIA-C and REL-C. Ihe exit code is as follows: 

END-IT. 

CLOSE ORKIR-^ILE. 

WRITE SCR FROM CIA-C. 

WRITE SCR FROM REL-C. 

CLOSE INbTLE. 

STOP 'END OF ORIXR ENTRY'. 
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CREATING THE FOFM DESCRIPTOR FILE 

The foregoing example shows how an application program might be coded 
and discussed reasons for using various codirg techniques. In 
addition, the user must describe the form to be used with the program. 
The data contained with the form, both on the terminal screen and in 
the data record must be described using the FDL translator and placed 
on the FORMS library (called the FORMS catalog) using the FAP command 
(see Section 6). The form descriptor specified by the user as a 
template that describes both how the form is to be displayed at the 
terminal and how it is to be stored, in terms of the attributes of the 
data items and the overall arranganent of the form. 

As stated in Sections 3 and 5, the FDL translator forms descripjtor 
language is available to make a source language description of v^at the 
form looks like both on the terminal ard in the data record. The 
syntax of FDL is summarized in Section 3 and described in Section 5. 
The following paragrapiis discuss how the form used by the sample 
application program is coded and tansiated. A complete listing of the 
sample form descrip>tion is given in /^pendix H. Features that are 
essential in every form descripjtion as well as spsecial features are 
discussed in this section together with excerp>ts of the FDL source 
code. Features discussed in detail are: 

• Setting up the FORMS descriptors 

• Defining the terminal devices used 

• Defining data areas (fields) 

• Differentiating input data from output data 

• Differentiating literal data and variable data 

• Spjecifying listing details 

The discussion is completed by a brief description of how to use the 
FDL larguage translator command and how the FDL checks for errors in 
the source language inpxit. This is followed by a discussion of how to 
install a form description in the FORMS catalog using FAP. 

Setting Ip Ebrm Description 

Every form description consists of twe parts: one to describe the data 
record, and the other to describe the form itself. These are the 
STREAM and the FORMAT descriptors respectively. The STREAM descriptor 
is bounded (defined) by a STREAM statanent and an END STREAM statement. 
Likewise, a FORMAT descriptor is bounded by a FORMAT and END FORMAT 
statement. In each form description, there need by only one STREM 
descriptor, since the internal data record need be only described once, 
ftjwever, there must be one FORMAT descriptor tor each typ)e of device 
the user wishes to use with the application program. An example of FDL 
code is shown in the following paragraphs. 


8 


9 


November 1979 


SECTia!^ 8 


PER3040 


Defining Device Types 


For each terminal connected to the system that interfaces with the 
applicaticai program, there must be a DEVICE descriptor. These 
descriptors are bounded by lEVICE and END DEVICE statanents and are 
contained within the body of the FORMAT dscriptor, as illustrated in 
the following FDL coding excerpts: 

DBl STREAM 

• • 

END STREAM 

ESI FORMAT 

ISIVICE OWL1200 

• • 

END DEVICE 
DEVICE VISTAR3 

• • 

END DEVICE 
END FORMAT 

Setting Up Data Areas (FIELDS) 

Data items are described by FIELD statements. FIELD statements may 
describe a literal, some system wide information, or may describe a 
variable. FIELD statements that describe a literal consist of the 
keyword FIELD and the literal in single quotes, for example: 

FIELD 'CUSTOMER NftME' 

Fields that give system information such as time and date are described 
in Section 5. FIELD statanents that describe variable (NOFROTECT) data 
items give the length of the field and the attributes of the data 
within the field, such as type, justification, validation, etc. There 
are differences between the format of a FIEID statement in a STREAM 
descriptor and a FIELD statanent in a FORMAT descriptor. For example, 
the field name in a STREAM-FIELD statemaot is contained within the body 
of the statanent following the keyword STREAM, and the field name of a 
FORMAT-FIELD Statement must appear in Column 1. However, there is a 
one-for-one mapping between the variable fields in a STREAM descriptor 
and the corresponding fields in the associated FORMAT descriptor. All 
of these practices are iiustrated in the tollowir^ code: 
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* DATA RECORD LAYOUT 

* 

SI STREAM 

* ACCOUNT NAME 

* 

AM FIELD NAM LENGTH 20 

* ADERESS 

* 

D1 FIELD ADI LENGTH 20 

D2 FIELD AD2 LENGTH 20 

D3 FIELD AD3 LENGTH 20 

* STOCK - ORDER INFORMATION 

* 

TKNNO FIELD STKNO LENGTH 6 

TKQTY FIELD STKQTY LENGTH 5 JUSTIFY RIGHT 

TKDEL FIELD STKDEL LENGTH 8 

* ORLffiR NUMBER - GENERATED BY PROGRAM AND OUTPUT 

* 

NO FIELD ONO LENGTH 5 OUTPUT 
END STREAM 

* END OF EATA RECORD DESCRIPTION 

********** 

* FORM DESCRIPTION 
SI FORMAT 

* FIRST lEVICE DESCRIPTION 

* 

DEVICE VISTAR3 

* HEADING INFORMATION OF FORM 

* 

FIELD 'ORDER ENTRY SYSTEM' POSITICW (22,2) 

FIELD '---' POSITION (22,3) 

FIELD 'ACCOUNT NAME ' POSITION (10,6) 

* ACCOUNT NAME INFORMATION 

AM FIELD LENGTH 20 POSITION (35,6) NOFROTECT 
FIELD ' AND ADDRESS' POSITION (10,7) 

* ACCOUNT AODRESS 

* 

D1 FIELD LENGTH 20 POSITION (35,7) NOPROTECT 

D2 FIELD LENGTH 20 POSITION (35,8) NOtROTECT 

D3 FIELD LENGTH 20 POSITICSN (35,9) NOFROTECT 

FIELD 'STOCK NUMBER' POSITION (10,12) 

* STOCK - ORDER INFORMATION 

* 

TKNO FIELD LENGTH 6 POSITION (35,12) NOFROTECT 
FIELD 'QUANTITY' POSITION (10,14) 

TKQTY FIELD LENGTH 5 POSITION (35,14) NOFROTECT 
FIELD 'DELIVERY DATE' POSITION (10,16) 

TKDEL FIELD LENGTH 8 POSITION (35,16) NOPROTECT 
FIELD 'ORDER REFERENCE IS' POSITION (10,20) 

NO FIELD LENGTH 5 POSITION (35,20) 

END DEVICE 

* END OF FIRST DEVICE ASCRIPTION 
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In this case, maFping has been performed by the programmer, by giving 
the STREAM fields the sane label as the corresponding FORMAT fields. 
Ifev^ver, this is not necessary if the STREAM variables are given the 
same name as the FORMAT labels. 

Input and Output Data 


The listing generated by FDL separates the STREAM description into two 
areas, one showirg INPUT field data and one showing OUTPUT field data. 
Refer to the listing in /^pendix H. If the user does not specify 
otherwise, all fields are both INPUT/OUi'PUr. An example of an OUTPUT 
field is illustrated by the following line of code; 

NO FIELD ONO, lENGTH 5, OUTPUT 

The listirg in P^jpendix H shows how FDL separates INPUT and OUTPUT 
fields. A check of this listing will reveal that the field ONO is 
present in the output description but not the input description. 

The variable (ONO) is not specified at the terminal by the user, it is 
generated and used internally by the program. Therefore, there is no 
reason for it to be specified as input, it only need be written on 
output. 

Literal and Variable Data 


Literal fields within a FORMAT are simply specified by the FIELD 
statement containing the literal string. For example: 

FIELD 'ACCOUNT NAME ' POSITIOl (10,6) 

Variable fields may be specified by using the NOiROTECT attribute. For 
example: 

FIELD LENGTH 30, POSITION (35,6), NOPROTECT 

Fields that may not be changed may prevent the user fron writing in 
them by use of the PROTECT attribute. (Refer to Section 5.) 

Specifying FDL Listing details 

FDL produces an output listirg unless the user ^ecifies otherwise. 
The user can control listing features with control statements such as 
LIST and NOLIST. Ciie advantage of the listing is that the user can 
check and be sure the data items in the STREAM portion of the 
description map properly to the corresponding data items the FORMAT 
portion. 

Finally, the FDL output listing shows additional useful information 
about the form description. First the items defined in the input 
stream and the output stream are listed in a separate cross-index after 
the listing of the translated STREAM code. For example, the header 
substream is output but not input information. Similarly, the listing 
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provides a convenient chart of lines and colunns for each lEVICE 
specified in the FORMAT descriptor. Bbr example, the last two pages of 
the output listing (named EGl) in Appendix H show the fields in their 
relative position location, show literal fields as they appear, and 
show the location of the variable (NOFROTECTED) fields by the lines of 
dashes. 


COMPILING THE APPLICATION FRCXmM 

The example program is compiled using the COBOL command, as follows: 

OK, COBOL DEMOl -64V -LIST 
GO 

PHASE I 
PHASE II 
PHASE III 
PHASE IV 
HIASE V 
PHASE VE 


NO ERRORS, 1 WARNINGS, P400/500 COBOL REV 15.3 <MAIN > 


OK, 


TRANSLATING THE FDL SOURCE 

The source description of the form must be input to the FDL translator, 
using the FDL conmand. The translation prodices an output file in a 
binary form v^iich may be placed in the FORMS catalog. Files listed in 
the FORMS catalog can be read and interpreted by the application 
program at run-time. The following is an example of the FDL 
translation for the sample form descriptor named ESI. 

OK, FDL DSl 
GO 

0000 ERRORS (FDL, REV 16 - 16-FEB-79) 

0000 ERRORS (FDL, REV 16 - 16-FEB-79) 

OK, 
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INSTALLING FCRM ffiSCRIPTOR IN FCRMS LIBRARY 

The FAR ccxrmand is used to install toms descriptors in the FOR'IS 
library and also maintain the FORMS catalog. The following is an 
example installation of the fom descriptor DGl in the FORMS catalog; 

OK, FAR 
GO 

FAR REV 16 23HDEC-78 

* ADD B-EBl 

3 DEFINITIONS AODED 

* QUIT 

OK, 


LOADING THE APPLICATION PROGRAM 


Since the sample program is written and compiled in V-mode the SEG 
loader must be used and the appropriate libraries invoked. This 
procedure is illustrated in the following example; 


OK, SEG 
GO 

# LOAD 

SAVE FILE TREE NAME; 
$ LO B_DEM01 
$ LIB VCOBLB 
$ LIB VKDALB 
$ LIB VFORMS 
$ LIB VSPOO$ 

$ LIB 

LOAD CCMPLETE 
$ SAVE 
$ QUIT 


#DEM01 

/* V-MODE COBOL LIBRARY */ 

/* V-MODE MIEAS LIBRARY */ 

/* V-MODE FORMS LIBRARY AND SHARED LIBRARY */ 
/* OFF-LINE PRINTING LIBRARY */ 

/* STANDARD SUBROUTINE LIBRARY */ 


OK, 
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MIDAS FILE TEMPLATE 

Since the example program, MMOl, uses the INDEXED feature of COBOL, 
the Prime indexed file system, MIDAS, is autcxnatically invoked. (Ihat 
is vhy the library VKDAIB was loaded.) Since MIDAS (indexed) files are 
used, it is necessary to create a tonplate using CREATK. The following 
code shows this procedure. For further information, refer to the MIEAS 
Inference Guide. 

OK, CREATK 
GO 

MINIMUM OPTIC»iS? YES 


FILE NAME? ORDERS 
NEW FILE? YES 
DIRECT ACCESS? I® 

DATA SUBFILE QUESTIONS 

KEY TYPE: A 
KEY SIZE = : B 7 
DATA SIZE = : ^ 

SECONDARY INDEX 

iNra:x NO.? 1 

DUPLICATE KEYS PERMITTED? YES 
KEY TYPE: A 
KEY SIZE = : B 20 
lEER DATA SIZE = : 0 


INDEX NO.? 2 

DUPLICATE KEYS PERMITTED? YES 

KEY TYPE: A 

KEY SIZE = : B_6 

USER DATA SIZE = : 0 


INDEX NO.? 3 

DUPLICATE KEYS PERMITTED? YES 

KEY TYPE: A 

KEY SIZE = : B_8 

USER DATA SIZE = : 0 


INDEX NO.? 0 
OK, 
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RUNNING THE PROCS^M 

The prog ran may be run by a simple invocation of the SEG command, 
example; 

SEG #DEM01 


for 
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APPEMDIX A 
INSTALLATION 


DIRECTORY INFORMATION 

The Forms Management Systan is supplied in a single directory on the 
master disk. Within this directory, named FORMS*, are subdirectories 
that contain source text for the ccmponents of the system and contains 
conmand files that are used to build the FORMS system. 

The files in the UFD named FORMS* are: 


Name 

Type 

FIX 

subUFD 

FAP 

subUFD 

RON 

subUFD 

lOS 

subUFD 

DOC 

subUFD 

FORMS* 

subUFD 

C RLIB 

command 

C VLIB 

canmand 

RFORMS 

object-file 

VFORMS 

object-file 

MACROS 

insert-file 

C_INST 

command 

C_Rnn 

comand 


File 

Description 

sources for FDL translator 

sources for FAP utility 

sources for run-time package 

sources for IOCS interface, device drivers 

source for design specification 

Skeleton FORMS catalog, systan files 

creates 64R library from individual object files 

cretess 64V library from individual object files 

64R mode FORMS run-time system 

64V mode FORMS run-time system 

$INSERT file containing sample FDL macro 

definitions 

installs new FORMS system 

upgrades current FORMS system to Rev. m 

(where nn is the current revision nunber.) 


INSTALLING A NEW VERSION OF FORMS 

Tb install the current version of FORMS on a system on v^ich there is 
no existing copy (i.e., to create a new FORMS installation): 


1) Use FUTIL to copy the FORMS* subUFD from the FORMS UFD to the MFD 
on any started up local disk, thus making FORMS* a first-level 
directory. FORMS will not vrork properly if the FORMS* directory 
resides on a disk on a remote system accessed via ERMENET. 

2) Execute the C_INST command file in the FORMS UFD to copy the FAP 
and FDL programs to OMD1SC0 and to copy the Rb’OFMS and VFORMS 
object files to the library UFD, LIB. The FORMS system is now 
ready for use. 

The following is an example run; user input is underlined. 


A 


1 


November 1979 



APPENDIX A 


Pm3040 


OK, MAGRST 

READY TO RESTORE: PARTIAL 
TREENME: MFD>FORMS* 

RESTORE COMPLETE 

OK, FUTIL 
>FROM FCRMS* 

>TO MFD XXXXXX 0 
>TRECPY FCRMS 
>FROM FCRMS > FAP 
>TO CMrM:0 
X:OPY *FAP > FAP 
>FRQM FCRMS > FDL 
X:OPY *FDL > FDL 
>FR0MS FCRMS* 

>TO LIB 

XZOPY RFORMS, WORMS, SFORMS 
>QUIT 


UPGRADING A CURRENT INSTALLATION 
lb upgrade an existing FOR4S installation: 


1) Execute the C_INST command file to copy the new run files to 
CMDNC0 and libraries to LIB. 

2) Execute the C Rnn command file. This will create the necessary 
files in the FORMS* directory to support Rev. nn . 

This procedure will not affect existing programs. The user is 
encouraged, however, to reload his prograns with the new libraries to 
take advantage of the improvements and additional features offered. 
Ihe following is an example run; user input is underlined. 

OK, MAGRST 

READY TO RESTORE: PARTIAL 
TREENME: MFD>FORMS * 

RESTORE COMPLETE 

OK, CO C INST 

• • • 

OK, CO C RUN 
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Note 

The existirg customer has the option of replacing the entire 
FORMS* UFD using the procedure for a new FCRi4S customer 
(previously described) and then adaing all the current FORM 
definitions (from scratch). ^eed improvanent and size 
reduction provided by a new library will only come to the 
user that reloads the application program with the new 
library. 


REBUILDING FORMS 


The following command files are available to rebuild all or part of the 
Forms Management System: 


Treename Descr iption 


FORMS> FDL> C_SUBS 
C_FDL 
C_LOAD 

FORMS> FAP> C_SUB 
C_FAP 
C_LCAD 

FORMS> RUN> C_FMR 
C_EMV 

FORMS >IOS> C_IOR 
C_IOV 

FORMS> C_RLIB 

C_VLIB 
C BLD 


compile FDL subroutines 
compile FDL main, load and save 
Load and save FDL 
compile FAP subroutines 
compile, load and save FAP 
load and save FAP 

compile 64R mode FORMS run-time package 
compile 64V mode FORMS run-time package 
compile 64R mode I/O system 
compile 64V mode I/O system 
build 64R mode library from objects 
build 64V mode library from objects 
build entire FORMS system. 


All command files described above generate no listing of the compiled 
source. For each command file viiich compiles source text, exists a 
corresponding command file, Vv^iich in addition to generating a binary 
(object) file, also produces a compilation listing. Ihe names of these 
command files may be determined by concatenating the standard command 
file name with the character 'L'. For example, to compile the 64R mode 
version of the run-time package and generate a listing, one wauld run 
the command file C FMRL instead of C FMR. 
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APPENDIX B 
DEVICE I-O 


EEVICE INPUT/OUTPUT SYSTEM 

This appendix describes the layout and operation of the device 
input/output system. It is most useful to those desiring knowledge of 
how FOFlMs works internally. Users vho must write their own device 
drivers will find information about writing device drivers in this 
appendix. 

Ihe device (Input/Output) system is logically associated with the 
run-time package and ccaisists of two parts. The first is an IOCS 
interlude to route all terminal and line printer I/O requests through 
FORMS. The second part performs all device mapping and input/output 
with any formatted device. 


IOCS INTERLUDE 

The IOCS interlude interfaces the Prime Input/Output Control System 
(IOCS) - refer to the Subroutine Reference Guide, Software Library - to 
FORMS through a series of input/output subroutines. Included in the 
IOCS interlude, are replacements for the standard read and write ASCII 
tables (RATBL and WATBL.) These tables cause FORMS subroutines I$FM01, 
O$FM01, and O$EM06 to be called to process terminal input, terminal 
output, and line printer output, respectively. Input and output is 
processed by I$FM01, O$FM01 and O$FM06 as described in the following 
paragraphs. 

• If the first two character positions in an output record 
contain two hash marks (#) , the output record is piassed to the 
FORMS directive interpreter (FM$CMD). 

• If no form is invoked on the associated device, the FORMS 
subroutine calls the standard IOCS subroutine for that device. 
O$AA01 is used for terminal output, I$AA12 for input. Line 
printer output is ignored, vhich is standard procedure in 
ERIMOS; another method is used to write files to the spwoler 
line printer. 

• If a form is in use on the associated device, the inpKJt/outpxit 
request is transferred to the FORMS subroutine EM$IN (input or 
EM$OUT output.) 


DEVICE I/O MECHANISM 

The device I/O mechanism interfaces the body of the FORMS run-time 
package to the formatted device(s) that are in use. This is 
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accomplished through a mapping scheme, and a collection of device 
driver subroutines, one for each device supported in the installation. 

Device Definition Database 


Two files exist in the FORMS UFD (FORMS*) that describe the device 
configuration of the installation; the device control file and the 
terminal configuration file. 

Device Control File ; Ihe device control file (called DCF.AS) describes 
each device in terms of a uni(^e logical device number (Idn) , device 
name, device driver subroutine name, and page capacity in lines and 
columns. 

The logical device number (not to be confused with an IOCS logical unit 
number, used in conjunction with the device driver subroutine name) is 
used to determine the execution time subroutine address for the device 
driver for a given device name. 

The device control file consists of a series of entries. The format 
for the device control file entries, which may be modified with the 
text editor, is as follows; 

Each entry describes one device. It consists of a single line of 
text with five items, each separated by ccsnmas as follows; 

Idn, device-name, device-driver-name, lines, columns 

Idn is the unique logical device number associated with the 
device. It must be in the range l<=ldn>=99. logical devices 1 
to 9 are reserved for use by Prime. User—written device 
drivers may use any Idn greater than 9. 


device-name is the 1 to 8 character device name. It must 
conform of the naming conventions set forth in the FDL 
description. 

device-driver-name is a two character abbreviation of the name 
of the device driver subroutine. The full name of the device 
driver subroutine is xx5I0; >oc is the two-character 
abbreviation. 

lines , columns defines the physical device page size. 

For example, the contents of the current device control file is; 

l,miNTER,PR,66,132 

3,VISTAR,V3,24,80 

41,OWL1200,OW,24,80 

Terminal Configuration File ; Another file exists that describes the 
device name for each FCiRi4S terminal on the system. Each user on the 
PRIMOS system is assigned a unique user number based on the physical 
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line to v^ich the terminal is connected. The terminal configuration 
file, (TCB.BN), specifies the terminal name for each of the up 64 FOMS 
user (terminals) connected to the system. The FAP utility is used to 
modify and inspect this file. 

Device Mapping Schane 


The following paragrajdis describe the mapping schane used by the 
run-time package. 

The FORMS run-time packages has a section of code to perform all 
initialization. Anong other functions, this obtains the device names 
for the terminal and printer. 

The terminal device name is obtained from the Iterminal Configuration 
File, based on the user nunber (assigned by ETilMOS). The printer name 
is specified in FORMS as PRINTER. 

When the device name is knom, the logical device nunber is otained 
iron the Device Control File. Two versions of the DCF exist. DCF.AS 
is the ASCII (edit) version that may be changed at any time by the 
user. DCF.BN is the binary version that is used by the run-time 
package. DCF.BN file is generated by FAP upon execution of the 
GENERATE ccanmand. Two versions of the file exist to ensure the active 
copy (DCF.BN) is concurrent with the device address tables. 

The logical device nunber is retained by FORMS and used to identify the 
device to the device interlude subroutine. This routine dispatches to 
appropriate device driver using a supplied unique locial device number 
(LDN). The dispatch operation is performed using device address 
tables. These tables are generated by FAP (using the GENERATE coitmand) 
and compiled into the I/O systan. Each table entry contains the 
address of a device driver. Position within the table corresponds to 
the logical device nunber. 

Two device address tables exist, one for the 64R mode version of the 
run-time package (called DEVDAC) , the other for 64V (EEVIP) . A third 
file declares each device driver external name (DEVEXT). These tables 
reside in the UFD naned FORMS*. 

The contents of the 64R device address table is: 


DAC 

FR$IO 

LDN 1 = IRINTER 

OCT 

0 

NO ENTRY WITH LDN 2 

DAC 

V3$I0 

LEW 3 = VISTAR3 

DAC 

OW$IO 

LE*J 4 = OWL1200 


PRIME-SUPPLIED DEVICE DRIVERS 
At present, FORMS supports the 
• offline printer 
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• Infoton Vistar/3 (modified) (VISTAR3) 

• Perkin-Elmer CWl (OWL1200) 

Offline Printer Device Driver 

The E>RINTER device driver writes a form (or forms) to the line-printer 
spool queue. When the INVOKE command is issued to the line printer 
(IOCS Logical Unit 4), a file called PRMuu (where represents the 

user nunber) is opened. If it already exists, the file pointer is 
positioned to the end of file, where the new form definition will be 
written. If it does not exist, it is created after a record is written 
containing the control code for the line printer to enter FORTRAN 
forms-control mode. 

When a form is output, one ASCII record is written for each line 
defined in the form. The first line contains a '1' in column 1, vhich 
causes the printer to eject to the top of a new page. Any enabled 
fields are underscored (with the _ character) . 

When the form is released, the file is copied into the spool queue, 
with the appropriate spool file header and file name. It is then 
closed and deleted from the home UFD. The rejfffuu file must never 
appear in the home UFD after the program has not been completed; if it 
does, it means that the FAINTER form was not released. 

Because of the new spool subsystem, two versions of PR$1I0 are 
supplied. Source file PR$IO contains the version of the printer driver 
that is compatible with the spooler. This is the subroutine that is in 
the IRFCRMS and VFORMS libraries as released on the master disk. Source 
file OPR$IO contains the printer driver that is compatible with the 
older version spooler. To rebuild the FORMS libraries to work with the 
old spool subsystan, rename PR$IO to N£»R$IO and then OPR$IO to PR$IO. 
Ihe I/O system may then be rebuilt with C_IOR and C_IOV, after vAiich 
the RFORMS and VFORMS libraries may be r^uilt with C_RLIB and C_VLIB, 
as outlined above. 

VISTAR/3 Device Driver 


The Infoton VISTAlVS device driver (V3$I0) is designed around a 
specially modified VISTAR/3 (with microcode and hardware updates) 
available through Prime. 

The device diinensions are 24 lines by 80 columns (1920 characters) , all 
of v^ich except the 15 character positions in the lower right of the 
screen are available for use by the application progran. These 
character positions contain one of the following prompt or error 
messages from the device driver: 

(spaces): 

input not allov^ 

ENTER 

enter data into unprotected fields on form. 
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press XMIT PAGE key viien done 

ERRCR, REHSNTER (blinking) 

a character vas lost on the last transmission - 
press XMIT PAGE key 

DATA ERROR (reverse video) 

a field (or fields) does not meet the specified 
validation criteria. The cursor is positioned to 
the first character position of the erroneous field 
correct the data and depress the 'XMIT PAGE' key 

All unprotected fields are displayed surrounded by square brackets 
(i.e., [ and ]) and are displayed in full intensity. All protected 
fields are displayed at half intensity. Care must be taken to allow 
for the square brackets on unprotected fields v^en designing the fom. 
The square brackets may be suppressed as an installation option by 
settirg the variable ENCL in the device driver (F0RMS>I0S>V3$I0) to 
zero. 


To operate the YISTAR/3 with a program using FORMS, the switches in the 
rear of the display must be set as follows: 


EOT character: 
mode: 

line-speed 
sec channel: 
parity: 
fduvhdux: 
stop bits: 
roll/page: 

Owl Device Driver 


CR 

block 

(user-selectable) 

off 

none 

(use r-sel ec t abl e) 
2 

roll 


The Perkin-Elmer OWL1200 device driver is designed for a stock OWL 
tenninal v\^ich is capable of supporting function keys. 

The device dimensions are 24 lines by 80 columns (1920) characters. 
The first character position, (1,1) and the last six character 
positions, (75,24) through (80,24), are not available for use by the 
form definition. Also, the character positions immediately preceding 
and following a field with any attribute other than protect must be 
vacant. 


When an input operation occurs, the data on the screen may be 
transmitted to the computer by using any of the SEND keys on the right 
hand keypad. If function keys are disabled, striking FI will also 
transmit the screen data. If function keys are enabled, striking any 
of the function keys will send the data to the computer and make 
available to the application program the nunnber of the function key 
depressed. The number of function keys maybe expanded tWD fold by 
using shift-Fh. This causes 16 to be added to the function key value. 
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When user input is required, one of the following prompt messages is 
printed in the lov^r right corner. 

ENTER 

Operator input is required - press one of the send or function 
keys when done. 

DATA? 

The data in the field to which the cursor is positioned does not 
conform to any of the validation criteria specified in the form 
definition. Re-enter the data and depress the SEND key. 

SEQ? 

The data v\as not trananitted fran the terminal in the proper 
sequence. This usually indicates that a character was lost 
during transmission. Press the appropriate SEND or function key 
again. 

SIZE? 

Too many characters v\ere sent for a given field in the form 
definition. This usually indicates that a character was lost 
during trananission. Press the appropriate SEND or function key 
again. 

No special switch settings are required when a FORMS program is run on 
the CWL. 
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INTRODUCTION 

If the user desires to interface FORMS with a device or terminal that 
is not provided for by the standard interfaces described in Section 6, 
then it is necessary that the user write a device driver. 

Techniques for this are discussed in the following paragraphs; 

Terminal Requirements 

Any terminal to be used with FORMS must have the following 
capabilities: 

• internally buffered (block transmission) mode 

• protected fields 

• absolute cursor positioning 

• data modification once displayed 

• clear entire screen/clear unprotected data commands 

Other features that could be taken advantage of by the FORMS system or 
device driver include: 

• blink 

• reverse video 

• underlining 

• keyboard lock 

• input and/or output space compression 
Device Driver Specification 


Device drivers must be named xx$IO, v^ere xx represents the 
two-character abbreviation used in the device control file. They have 
the following calling sequence: 

CALL xx$IO (function, iolist) 

Function is one on the following nine function codes; 


Function 

Number Meaning 


1 Initialize device; Reset all device logic, clear the entire 
screen, and enter block transmission mode (if this is a 
software function) . 

2 Output initial form: Write the contents of the entire I/O 
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data list (lOLIST) to the screen. Ihe device driver should 
reset bits 1, 2, 3, and 4 of the attribute word for each entry 
and set bit 5 for each field displayed. It must not display 
any fields with the NODISPLAY bit 'bit 14) set. The location 
of the cursor following the output operation may be undefined. 

3 Input form: First, the cursor must be positioned as follows: 

• if EEV3M$ variable XPOS is zero, the cursor must be 
placed at the first character position of the first 
unprotected field displayed on the terminal. The DEV3M$ 
common block is described later. 

• if XPOS is non-zero, the cursor must be positioned to 
location (XPOS, YPOS) on the device. 

The device driver must v\rait for the user to fill in the 
displayed form and process the input as it is transmitted from 
the terminal. As it receives the data, the driver is 
responsible for inserting it into data areas in each field in 
the I/O list. Only fields with the DISPLAYED and ENABLED bits 
set in the attribute word must be input. On a fill duplex 
line, the device driver must disable the echo and 
auto-iinefeed generation with a call to DUPLX$; this must be 
restored after the data has been input. If possible, a brief 
prompt message should be displayed in a convenient place on 
screen, informing the user that there is an input request 
pending. 

If a function key was depressed, the device driver must check 
the logical variable FKEYS in the EEVCM$ ccwmon block. If 
OFF, refuse the function key request by waiting for the proper 
transmit key to be typed. If FKEYS is ON, save the function 
key number in the DEVZM$ variable FKEYNO (integer) and process 
the data as described above. 


4 Modify existing form: Ihe device driver must examine each 
entry in the I/O list and update those fields with attribute 
bits 1, 2, or 4 set. Ihe recommended logic for the modify 
processor is: 

• if data changed, enable/protect changed, or field 
attribute changed bits are all reset, process next 
field; else save current attribute word in a temporary 
storage area, and reset bits 1-4 (dat^attr ibutes 
modified) of the attribute word in lOLIST 

• extract field length, and x,y, coordinates from lOLIST 

• if the field is currently displayed and 'NODISPLAY' bit 
is set, erase this field from display, reset bit 5 in 
lOLIST entry, and process next field; else if field is 
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not currently displayed and 'NODISPLAY' bit is reset, 
display the field according to the supplied attributes 
and x,y, coordinates and set bit 5 in lOLIST entry; 
else if 'NODISPLAY' bit is set, ignore this field and 
process next; else if enable/protect changed bit is set 
and special handling is required to acccxnodate this 
change, perfom this special handling. 

• if attribute changed bit is set, update the field using 
the new attributes and process the next field; else 
update the data and process the next field. 


5 Clear entire screen. All information displayed on the screen 
should be erased. 

6 Clear unprotected data on screen. All unprotected information 
on the screen should be erased. 

7 Close device: This function code is used to terminate device 
usage after a RELEASE cortmand and is applicable primarily to 
the line-printer driver; terminal device drivers should 
switch the teminal back to conversational mode. 

8 Correct data: The device driver must scan the I/O list for 

the first field with the 'data-invalid' attribute bit set (see 
below) , position the cursor to the first character position of 
this field, and allow the operator to re-enter the data. It 
is recommended that an error/prompt message be displayed, 

informing the operator that the specified field has failed all 
validation tests and that it must be re-entered. This message 
should be displayed on a part of the screen that does not 
interfere with the form. 

9 Print local: Write the contents of the entire screen to the 

local printer attached to the terminal; this feature must be 

supported by the particular terminal hardware in use. The 

device driver should return to the caller when the printer has 

completed printing. 

lolist is an array that contains the control and data definitions for 
each field in the form. It contains header WDrds and at least 1 data 
word for each entry. The array must be accessed by the device driver 
using a pointer to the beginning of the field (supplied by the run-time 
package) added to an offset. Ihis offset should be specified in the 
form of a PARAMETER'ed symbol, as defined below. 

The following PARAMETERS represent each of the control words, plus the 
start of the data area. The device driver should be oblivious to their 
actual values, as these may change vdien new control information is 
added. The parameter declarations may be made thru a $INSERT file 
called 'I0PAH4' in the directory containing the source of the I/O 
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system (e.g., as released, FCRMS>IOS>IOPARM) . 
Parameter Meaning 


lOLK Link to next entry in chain by position; this is not used 
by device drivers 

lOVP stream definition field pointer for this entry; this is not 
used by device drivers 

lORP format definition field pointer for this entry; this is not 
used by device drivers 

lOSZ field length, in characters 

lOAT field attributes, as follows: 

Bit Definition 


1 Set by FCRMS if data has changed since last display; reset 
be device driver when data has been updated on device. 

2 Set by FORMS if enable/protect attribute has changed since 
last display; reset by device driver v^en field has been 
updated on device. 

3 Set by FORMS if field has failed all supplied validation 
tests; reset by device driver vrtien field has been 
re-entered from device. 

4 Set by FORMS if any field attributes have been modified 
since last display; reset by device driver vrtien field has 
been updated on device. 

5 Set by device driver if field is currently displayed on 
device; reset by device driver if field is currently not 
displayed on device (initially reset) . 

13 Set by FOFMS if field should be blinked when displayed; 
reset by FORMS if field should not be blinked vi^en 
displayed. 

14 Set by FORMS if field should not be displayed or should be 
erased if currently displayed; reset by FOFMS if field 
should be displayed. 

15 Set by FOERMS if field should be displayed in reverse video; 
reset by FORMS if field should be displayed in normal video. 

16 Set by FCFM4S if field should be write-enabled, (not 
protected); reset by FORMS if field should be 
write-protected. 
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lOYX line and column coordinates: 

. left byte = line # (Y) 

. right byte = colunn # (X) 

lOPG physical page #; this is not used by device drivers 

lODA start of text data; data is in ascii format, packed 2 
characters per word, blank filled 


The initialize, clear, close, and print functions (1, 5, 6, 7, and 9) 
are all relatively straightforward. “Ihese operations do not have to 
process data from the I/O list and therefore should assume it to be 
void. 

The output, input, modify, and correct functions (2, 3, 4, and 8) all 
need to traverse the I/O list and process (or at least inspect) each 
field therein. The device driver must depend on the run-time system to 
provide a pointer for the start of each field definition in the I/O 
list. The run-time package contains twa subroutines callable by the 
device driver for such a purpose. Tiiey are; 

Subroutine Elinction 


FMS$RE resets the internal (run-time package) field pointer to the 
beginning of the current page. This routine must be called 
at the beginning of the output, input, modify, and 
correct-data function processors. It may be called again to 
reset the pointer to the first field in the page when 
necessary (e.g, on an input error) . 

Calling Sequence; 

CALL FMS$RE 

FMS^F returns the pointer to the next field in the I/O list to be 
processed. If the pointer is 0, the end of page or end of 
I/O list has been encountered. Fields are returned to the 
caller in line/colunn sequence. 

Calling Sequence; 

CALL FMS5NF (pointer) 

A common definition $INSERT file must be included in the device driver 
by the directive "$INSERT FORMS>RUN>EEVCM$". The conmon block contains 
4 variables wiiich are used by the input form (function 3) processor. 
They are; 
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Variable 


Function 


FKEYS Logical variable set to true if function keys are enabled, 
false if disabled. If a functicxi key is struck and FKEYS is 
false, the function key should be ignored; if true, the 
function key nunber should be stored in FKEYNO. 

FKEYNO 16 bit integer vAiich is set by the device driver to the 
nunber of the function key depressed. Should only be set if 
FKEYS is true. 

XPOS 16 bit integer column number v^ich the cursor is to be 

positioned prior to an input operation. If zero, position 
the cursor to the first enabled character position on the 
display. 

YPOS 16 bit integer line number for cursor positioning prior to 
input. It is only valid of XPOS is non-zero. 


A template for a device driver is included with the FC«MS system. It 
is suggested that the user follow this template vidien writing a device 
driver. 


INSTALLING THE DEVICE DRIVER 

To install a new device driver into the FCmS run-time library, the 
user should follow the steps outlined loelow: 

• Obtain a listirg of the device control file and choose a free 
logical unit nunber above 10 (the first 10 are reserved by 
Prime). Append an entry to the DCF containing the selected 
logical unit nunber, device name, first 2 characters of the 
driver name (remember, the last 3 must be '$10'), and the 
dimensions of the device in accordance with the format described 
in the section entitled "Device Mapping Scheme", above. For 
example, the Vistar/3 entry, whose logical unit nunber is 3, 
driver name is 'V3$I0', and dimensions are 24 by 80, would look 
as follows; 

3, VISTAR3, V3, 24, 80 

• Attach to the directory containing tlie source for the 
Input/Output System and copy into it the source for the device 
driver to be installed. 

• Edit the C_I0R (64R mode) and C_I0V (64V mode) command files and 
inset a line to compile the new device driver after the FR$I0 
routine. 

• Run FAP and issue the CSNERATE command to create the new device 
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tables and DCF v^iich will include the new driver. 

• Execute the C_ICR and/or C_IOV command file(s) to create a new 
input/output system. 

• Attach to the first-level FORMS source directory ('FORMS') and 
execute the ccxnmand file 'C_RLIB' to create a 64R mode library 
an(d/or C_VLIB to create a 64V mode library. 

The user may now modify the TC6 entries for the users that have the new 
terminal and reload application programs with the new version of the 
library. It is strongly recamnended that the new library not be 
installed in the UFD named LIB uitil the new device driver has been 
tested. 
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PROBLEM; FAP: lOISIZ Overflow Error (F03) 

SOLUTION; Change Default lOLSIZ Td Necessary 
Size And Rebuild FAP. 


1. In FORMS>FAP>IOBUF$; 

Change lOISIZ Parameter (Default = 2500) 
Td l^fecessary Size. 

2. Reouild FAP; 

Run Command Files In FCXRMS>FAP; 

C_SUBS 

C_FAP 

CJLOAD 

3. Copy *FAP Into CMENC0 As FAP 

4. Kin FAP ^ain To Replace Ihe FDL Binary 
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PROBLEM: Runtime I/O Error: lOLSIZ Overflow 

SOLLfTION: Change Default lOLSIZ Tb Itecessary Size 

And Rebuild FORMS Runtime Manager (RFORMS, 
WORMS, SFORMS) 


STEPS : 

1. In FORMS>RUN>IOLDEF: 

Change lOISIZ Parameter (Default = 2500) 
lb Necessary Size. 

*2. Rebuild Runtime Package: 

In FORMS>RUN, RUN Command File: 

C_BMV 

C_FMR 

In FORMS, Run Command File: 

C_VLIB 

CJRLIB 

*3. Copy WORMS, RFORMS Into LIB. 

4. Reload Your Program. 


*NOTE: If Running R-Mode Only Or 

V-Mode Only, 

Run /^propriate Command Files 
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PROBLEM: Adding A New Device Driver 

SOLUTION: Add Driver Parameters lb DCF.AS 
And Rebuild I OS With New Driver. 


STEPS : 

1. In FORMS*: 

Edit DCF.AS 

Add Parameters Ebr New Driver: 

For Example: lb Add Logical Device Number 4 , 
Device Name X!^123, Device ESriver Name XY, With 
24 Lines, 80 Colons; Insert The Line: 

4,)Ciri23, Xy, 24, 80 

2. Roi FAP Generate (Produces 3 $INSERT Files Which 
Contain Information i4)out Ihe New Driver Necessary 
In Building Runtime Library) 

3. IN FCRMS>IOS 
RUN C_IOR/C_IOV 

lb Change BIOR/BIOV 

4. In FORMS 

RUN C_VLIB, C_RLIB 

5. Copy VFORMS/RFORMS To LIB 

6. Execute Appropriate FAP TCB Command To ^lecify 
New Terminal For Specific User Nunbers. 

(Refer To Section 4) 

7. Reload Your Program With New Library. 
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APPENDIX E 

SAMPLE FORTRAN PROC3W1 


This appendix is a complete listing of the example program discussed in 
Section 7. 
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(0001) C ATSINP, FORMS, JRW, 78/02/23 
(0002) C REVISED 1979 MLG, 79/06/06 

(0003) C FORMS DEMO PROGRAM - INPUT ATS INFO, STORE IN DISK FILE 
(0004) C COPYRIGOT 1979, PRME COMPl/TER INC, FRAMINGHAM 
(0005) C 
(0006) C 

(0007) C-THIS PROGRAM INPUTS ATS INFORMATION FROM THE TERMINAL AND 

(0008) C STORES THE INFO IN A DISK FILE. 

(0009) C 

(0010) C IWO FILES ARE USED; 

(0011) C 

(0012) C ATS.C IS THE CONTROL FH£ - IT COIIAINS THE NEXT ATS NUMBER TO BE 

(0013) C ASSIGNED. 

(0014) C ATS.D IS THE EATA FILE. AS EACH ATS FORM IS ENTERED, IT IS APPENDED 

(0015) C TO THIS FILE IN THE FOFMAT SHOWN IN THE PROGRAM. 

(0016) C 
(0017) C 

(0018) C-TO TERMINATE THE PROC3RAM, ENTER A NULL NAME FIELD. 

(0019) C 

(0020) C-TO ENTER MORE THAN 4 ITEM LINES, ENTER A NON-SPACE CHARACTER (EXCEPT N) 

(0021) C IN THE 'MORE' FIELD. 

(0022) C 

(0023) C-THIS PROaiAM MAY BE USED BY A SINGLE USER IN ANY GIVEN DIRECTORY AT 

(0024) C ONE TIME. NO PROVISION IS MADE FOR CONCURRENT ACCESS TO THE DATA FILES. 
(0025) C 
(0026) C 
(0027) C 

(0028) COMMON /F$IOBF/ B(150) /* EXTENDED I/O BUFFER 

(0029) C 

(0030) INTEGER NAMAER(75), VIA, HOW, REPL, INTC, BILL, SaJUM(4), 

(0031) + CH3NUM(4), CPO(4), ACOTHR(15), AIRSPR, INS (5) , 

(0032) + TYPE, CODE, NWIO, ATSNU4, B, I, J, MORE, FLD1(4,4), 

(0033) + YESNOB(4) , ACTOUF(4,3), FLD2(4,3) 

(0034) C 

(0035) INTEGER PART(8,4), DESCR(15,4), SN(4,4), QTY(4) , RTN(4) 

(0036) C 

(0037) LOGICAL HDROUT 

(0038) C 
(0039) C 

(0040) EQUIVALENCE (YESNOB(1),REPL), (YESNOB(2),INTC), 

(0041) + (YESNOB (3) ,BILL) , (YESNOB (4) ,AIRSPR) , 

(0042) + (ACreUF(l,l),SONUM) , (ACIBUF(1,2),CH3NUM), 

(0043) + (AC'IBUF(1,3) ,CPO) 

(0044) C 
(0045) C 

(0046) C SYSCOM>KEYS.F MNEMOJIC KEYS FOR FILE SYSTEM (FTN) 31 MAY, 1977 

(0046) NOLIST 

(0047) C 
(0048) C 

(0049) DATA FIDl /'REPL ','INTC ','BILL ','AIRSPARE'/ 

(0050) DATA FLD2 /'SONUM ' ,'CHGN ' ,'CEO '/ 

(0051) C 
(0052) C 


REV. 0 
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(0053) 

(0054) 

(0055) 

(0056) 

(0057) 

(0058) 

(0059) 

(0060) 

(0061) 

( 0062 ) 

(0063) 

(0064) 

(0065) 

(0066) 

(0067) 

(0068) 

(0069) 

(0070) 

(0071) 

(0072) 

(0073) 

(0074) 

(0075) 

(0076) 

(0077) 

(0078) 

(0079) 

(0080) 

(0081) 

(0082) 

(0083) 

(0084) 

(0085) 

(008b) 

(0087) 

(0088) 

(0089) 

(0090) 

(0091) 

(0092) 

(009J) 

(0094) 

(0095) 

(0096) 

(0097) 

(0098) 

(0099) 

( 0100 ) 

( 0101 ) 

( 0102 ) 

(0103) 

(0104) 

(0105) 


C-EXTEND TERMINAL, FILE I/O BUFFERS. 

C 

CALL ATTDEV(1,1,0,150) 

CALL ATTDEV(6,7,2,150) 

C 

C CALL TO SHARED LIBRARY 

CALL FORM$I 
C 

C-OPEN FILES, INVOKE FORM ON TERMINAL. 

C 

CALL SRCH$$(K$CLOS,0,0,1,0,CODE) 

CALL SRCH$$(K$CLOS,0,0,2,0,COra:) 

C 

CALL SRCH$$ (K$RDWR,*ATS.C* ,5,1,TYPE,CODE) 

IF (CODE.NE.0) Call ERRPR$ (K5NRTN,CODE,'ATS.C* ,5,0,0) 

CALL SRCH$$ (K9REWR,' ATS. D*,5,2, TYPE,CODE) 

IF (CODE.NE.0) CALL ERRPR$ (K$NRTN,CODE,' ATS.D* , 5,0,0) 

C 

CALL FRWF$$(K$POSN4K$PRER,2,LOC(0) ,0,10000000,NWIO,CODE) 

C 

WRITE (1,20) 

20 FORMAT (' ##INVOKE ADMN377 ') 

C 

C 

C-^ASSIGN NEXT ATS #. 

C 

100 CALL PRWF$$(K$POS1HK$PREA,1,LOC(0) ,0,000000,NWIO,CODE) 

READ (5,120,ERR=160,ENU=160) ATSNUM 
120 FORMAT (16) 

GO TO 200 
C 
C 

C-HERE ON ECF, ETC. 

C 

160 ATSNIJM:^ 

C 

C 

C-^ASSIGN NEXT SEQUENTIAL ATS #. 

C 

180 ATSNIM=ATSNIM+1 

C 

C 

C-WRITE ATS#, CLEAR VARIABLE DATA, ERROR MESSAGE. 

C 

200 WRITE (1,210) ATSNIM 

HDROUr=.FALSE. /* HEACER NOT OUTPUT TO DISK FILE 

210 FORMAT (*##SUBSTREAM HEADER VI6/'##CLEAR*/* ##SUB STREAM ERROR'/* *) 

C 

C 

C-^READ IN NAMES, ADDRESSES, AND ACCOUNTING INFORMATION. 

C 

220 READ (1,240) NAMADR, VTA, HOW, REPL, INTC, BILL, SONUM, 

+ CHGNUM, CPO, ACOTHR, AIRSPR, INS 
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(0106) 

(0107) 

(0108) 

(0109) 

( 0110 ) 

( 0111 ) 

( 0112 ) 

(0113) 

(0114) 

(0115) 

(0116) 

(0117) 

(0118) 

(0119) 

( 0120 ) 

( 0121 ) 

( 0122 ) 

( 0128 ) 

(0124) 

(0125) 

(0126) 

(0127) 

(0128) 

(0129) 

(0130) 

(0131) 

(0132) 

(0133) 

(0134) 

(0135) 

(0136) 

(0137) 

(0138) 

(0139) 

(0140) 

(0141) 

(0142) 

(0143) 

(0144) 

(0145) 

(0146) 

(0147) 

(0148) 

(0149) 

(0150) 

(0151) 

(0152) 

(0153) 

(0154) 

(0155) 

(0156) 

(0157) 

(0158) 


C 

IF(NAMAER(1) .EQ.* ') GO TO 5000 /* BLANK NAME => EXIT 

240 FOR'IAT (75A2/211, 3A1,12A2,15A2, Al, 4A2,A1) 

C 

C 

C-^VALIDATE INPUT EATA. 

C 

IF (VIA.LT.1.0R.VIA.GT.9) GO TO 1000 
IF (HaW.LT.l.OR.HOW.GT.4) GO TO 1020 
C 
C 

C-CHECK YES/NO RESPONSES. 

C 

DO 250 1=1,4 

IF (YESNOB(I).GE.'a'.AND.YESNOB(I).LE.'z') /* MAP => UPPER CASE 
+ YESNOB(I)=AND(YESNOB(I) ,:157777) 

IF (YESNOB(I).NE.'Y'.AND.YESNOB(I).NE.'N') GO TO 1040 
IF (I.EQ.4) GO TO 250 

IF (YESNOB(I).EQ.'Y'.AND.AC'IBUF(l,I).EQ.' ') GO TO 1060 
IF (YESNOB(I).EO.'N'.AND.ACTBUF(1,I) .NE.' ') GOTO 1080 

250 CONTINUE 
C 
C 

C -GET ITEM EATA. 

C 

400 READ (1,420) ((PART(J,I) ,J=1,8) , (DESCR(J,I) ,J=1,15) , 

+ (SN(J,I) ,J=1,4) , QrY(I), RTO(I), 1=1,4), MORE 

420 FORMAT(4 (7A2,Al, 15A2,4A2,14,Al) ,A1) 

C 

C 

C-CHECK INPUT DATA VALIDITY. 

C 

500 DO 520 1=1,4 

IF (DESCR(1,I) .EQ.' ') GO TO 520 /* IGNORE BLANK LINE 

IF (R'IN(I) .GE.'a'.AND.RIN(I) .LE.'z') /* MAP => UPPERCASE 
+ RTN(I)=AND(RTN(I) ,;157777) 

IF (R'IN(I) .NE.'Y'.AND.RlNd) .NE.'N') GOTO 1100 
520 CONTINUE 

C 
C 

C-WRITE DATA TO DISK FILE. 

C 

DO 550 1=1,4 

IF (DESCR(1,I) .EQ.' ') GO TO 550 /* IGNORE BLANK LINE 

IF (HDROUT) GO TO 540 
C 
C 

C-WRITE ACCOUNT HEADER TO DISK FILE. 

C 

WRITE (6,525) ATSNIM, l^AER, VIA, HOW, REPL, INTO, BILL, SONU^l, 
+ CHGNUM, CPO, ACOTHR, AIRSPR, INS 

525 FORMAT ('*ATS', 16/5 (15A2/) ,211,3A1,12A2A5A2/A1,4A2, Al) 

C 
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(0159) HDROUr=.TRUE. 

(0160) C 

(0161) C 

(0162) C-WRITE INDIVIDUAL ITEM LINE TO DISK FILE. 

(0163) C 

(0164) C 

(0165) 540 WRITE (6,545) (PART(J,I) ,J=1,8) , (DESCR(J,I) ,J=1,15) , 

(0166) + (SN(J,I) ,J=1,4) , CfrY(I) , RTN(I) 

(0 167 ) 545 F0RMAT(7A2,A1,15A2,4A2,I4,A1) 

(0168) C 

(0169) 550 CCMINUE 

(0170) C 

(0171) C 

(0172) C-CHECK FCR MCRE ITEM LINES. 

(0173) C 

(0174) IF (MORE.EQ.' ' .OR.MCRE. EQ.'N' .OR.MORE. EQ.' n') GO TO 180 

(0175) C 

(0176) WRITE (1,580) 

(0 177 ) 580 FORMATClfttSUBSTREAM ITEMS'/' '/'ttSUBSTREAM ITEMS'/ 

(0178) + '##P0SITICN PART0i') 

(0179) GO TO 400 /* NEXT SET OF ITEM LINES 

(0180) C 

(0181) C 

(0182) C-INCORRECT DATA IN ACCOUNTING FIELDS. 

(0183) C 

(0 1 84) 1000 WRITE (1,1010) 

(0185) 1010 FORMAT ('##SIBSTREAM ERROR'/ 

(0186) + 'via ccxie must be 1-9'/ 

(0187) + 'IDPOSITION SHIPVIA') 

(0188) GO TO 220 

(0189) C 

(0 190) 1020 WRITE (1,1030) 

(0191) 1030 FORMAT('##SUBSTREAM ERROR'/ 

(0192) + 'how code must be 1-4'/ 

(0193) + '##POBITION SHIFHOW') 

(0194) GO TO 220 

(0195) C 

(0196) C 

(0197) C-^YES/NO ANSWER REQ'D. 

(0198) C 

(0199) 1040 WRITE (1,1050) (FLD1(J,I), J=l,4) 

(0200) 1050 FORMAT('##SUBSTREAM ERROR'/ 

(0201) + 'yes/no (Y or N) response required'/ 

(0202) + '##POSITION ',4A2) 

(0203) GO TO 220 

(0204) C 

(0205) C 

(0206) C-^ACCUMT NLMBER FIELD BLANK. 

(0207) C 

(0208) 1060 WRITE (1,1070) (FLD2(J,I), J=l,4) 

(0209) 1070 FORMAT('##SUBSTREAM ERROR'/ 

(0210) + 'account # required for YES response'/ 

(0211) + 'Jt#POSITION ',4A2) 
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( 0212 ) 
(0213) 
(0214) 
(0215) 
(0216) 
(0217) 
(0218) 
(0219) 
( 0220 ) 
( 0221 ) 
( 0222 ) 
(0223) 
(0224) 
(0225) 
(0226) 
(0227) 
(0228) 
(0229) 
(0230) 
(0231) 
(0232) 
(0233) 
(0234) 
(0235) 
(0236) 
(0237) 
(0238) 
(0239) 
(0240) 
(0241) 
(0242) 
(0243) 
(0244) 
(0245) 
(0246) 
(0247) 
(0248) 
(0249) 
(0250) 


GO TO 220 
C 
C 

C-^SURPLUS ACCOUNT NIMBER. 

C 

1080 WRITE (1,1090) (FLD2(J,I), J=l,4) 

1090 FORMAT ('##SUBSTREM ERROR'/ 

+ 'account if not permitted for NO response'/ 

+ '##POSITION ',4A2) 

GO TO 220 
C 
C 

C-RETURN CODE FIELD BLANK. 

C 

1100 WRITE (1,1110) I 

1110 FORMAT ('##SUBSTREiiM ERROR'/ 

+ 'yes/no (Y or N) response required'/ 

+ '##POBrnON RTO',B'##'/ 

+ '}f#SUBSTREAM ITEMS') 

GO TO 400 
C 
C 

C-^HERE TO EXIT. UTOATE ATS # IN CONTROL FILE. 

C 

5000 CALL FRWF$$(K$POSN+K$PREA,1,LOC(0) ,0,000000,NWIO,CODE) 
WRITE(5,120) ATSNUM 

CALL PRWF$$(K$rRNC,l,LOC(0) ,0,000000,NWIO,CODE) 

C 

CALL SRCH$$(K$CLOS,0,0,1,0,CODE) 

CALL SRCH$$ (K$CLOS,0,0,2,0,COEE) 

C 

WRITE (1,5020) 

5020 FORMAT('##CLEAR ALL'/'##RELEASE') 

C 

CALL EXIT 
C 
C 

c 

END 


PROGRAM SIZE: PROCEDURE - 002564 LINKAGE - 000502 STACK - 000022 

0000 ERRORS [<.MAIN.>FTN^V15.3] 
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FORM ffiSCRIPTOR FOR 
FORTRAN PROGRAM EXAMPLE 


This a^Jendix is a complete listing of the example fom descriptor 
associated with the program discussed in Section 7. 
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( 0001 ) 

( 0002 ) 

(0003) 

(0004) 

(0005) 

(0006) 

(0007) 

(0008) 

(0009) 

( 0010 ) 

( 0011 ) 

( 0012 ) 

(0013) 

(0014) 

(0015) 

(0016) 

(0017) 

(0018) 

(0019) 

( 0020 ) 

( 0021 ) 

( 0022 ) 

(0023) 

(0024) 

(0025) 

(0026) 

(0027) 

(0028) 

(0029) 

(0030) 

(0031) 

(0032) 

(0033) 

(0034) 

(0035) 

(0036) 

(0037) 

(0038) 

(0039) 

(0040) 

(0041) 

(0042) 

(0043) 

(0044) 

(0045) 

(0046) 

(0047) 

(0048) 

(0049) 

(0050) 

(0051) 

(0052) 


PRIMEATS, FORMS, XXX, 79/02/12 

* FRIMEATS, FORMS, XXX, 79/02/12 

* H^IME AUTHORIZATION TO SHIP FCRM — FORMS DEMO 

* COP^IGHT 1979, PRIME COMPUTER, FRAMINGHAM l^IA 

* 

* 

AEMN377 STREAM 

* 

LIST 

* 

* 


* - HEADER INFORMATION. 

* 

HEATER SUBSTREAM 

FIELD (FORMNAME,FOIWNAME) 

FIEID ATSNIM, LENGTH 6, JUSTIFY RIGHT, ZERO-F*ILL, OUTPUT 
END SUBSTREAM 

* 

* 

* -SHIP TO NAME AND AKHESS. 

* 

NAMAER SUBSTREAM 

FIELD NAME, LENGTH 30, VALIDATE 'P' OR 'B' 

REPEAT 3 

FIELD hWR, LENGTH 30 
END REPEAT 

* 

FIELD ATTN, LENGTH 30 
END SIBSTREAM 

* 

* 


* -SHIP VIA / HOW, ACCOUNTING, MISC INFO. 

* 

GENERAL SUBSTREAM 

FIEID SHIPVIA, LENGTH 1, VALIDATE '9' OR 'B' 
FIELD SHIPHOW, LENGTH 1, VALIDATE '9' OR 'B' 


FIELD 

REH., 

LENGTH 

1, 

VALIDATE 

'A' OR 

'B' 

FIELD 

INTC, 

LENGTH 

1, 

VALIDATE 

'A' OR 

'B' 

FIELD 

BILL, 

LENGTH 

1, 

VALIDATE 

'A' OR 

'B' 


FIELD SONUM, LENGTH 8, VALIDATE '99-99999' OR 'B' 

FIELD CHON, LENGTH 8, VALIDATE '99-99999' OR 'B' 

FIELD CPO, LENGTH 8, VALIDATE '99-99999' OR 'B' 

FIELD ACCOTHER, LENGTH 30 

FIELD AIRSPARE, LENGTH 1, VALIDATE 'A' OR 'B' 

FIELD INS, LENGTH 9, JUSTIFY RIGHT, ZERO-FILL, VALIDATE 'F' 
END SIBSTREAM 


* -ITEM INFORMATION. 

* 

ITEMS SUBSTREAM 
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(0053) 

(0054) 

(0055) 

(0056) 

(0057) 

(0058) 

(0059) 

(0060) 

(0061) 

(0062) 

(0063) 

(0064) 

(0065) 

(0066) 

(0067) 

(0068) 

(0069) 

(0070) 

(0071) 

(0072) 


REPEAT 4 

FIELD PART, LENGTH 15, JUSTIFY RIGHT, SPACE-FILL 
FIELD ffiSCR, lENGIH 30, JUSTIFY LEFT 
FIELD SN, LENGTH 8, JUSTIFY RIGHT, ZERO-^’ILL 
FIELD QTY, LENGTH 4, JUSTIFY RIGHT, ZERO-FILL, VALIDATE ' 
FIELD RTN, LENGTH 1, VALIDATE 'A' OR 'B' 

END REPEAT 

FIELD MORE, LENGTH 1, VALIDATE 'A' OR 'B' 

END SUBSTREAM 

* 

* 

* -ERROR / WARNING MESSAGE. 

* 

ERROR SUBSTREAM 

FIELD ERR, LENGTH 40, OUTPUT 
END SUBSTREAM 

* 

★ 

* 


END STREAM 


0000 ERRORS (FDL, REV 15 - 16-FEB-78) 

INPUT STREAM DESCRIPTOR STREA4: ADMN377 


SLBSTREAM 

SIBSTREAM 

COLIMN 

FIELD 

FIELD 

NAME 

NUMBER 

BOUNDARIES 

NAME 

LENGTH 

nAMAER 

2 

1- 30 

NAME 

30 

NAMADR 

2 

31- 60 

ADDR01 

30 

IMAMAER 

2 

61- 90 

ADER02 

30 

NAMAER 

2 

91-120 

ADDR03 

30 

nAMAER 

2 

121-150 

ATTN 

30 

GENERAL 

3 

1 

SHIPVIA 

1 

general 

3 

2 

SHIPHCW 

1 

GENERAL 

3 

3 

REPL 

1 

general 

3 

4 

INTC 

1 

GENERAL 

3 

5 

BILL 

1 

general 

3 

6- 13 

SONUM 

8 

GENERAL 

3 

14- 21 

CHGN 

8 

general 

3 

22- 29 

CPO 

8 

GENERAL 

3 

30- 59 

ACCOTHER 

30 

general 

3 

60 

AIRSPARE 

1 

GENERAL 

3 

61- 69 

INS 

9 

ITEMS 

4 

1- 15 

PART01 

15 

ITEMS 

4 

16- 45 

DESCR01 

30 

ITEMS 

4 

46- 53 

SN01 

8 

ITEMS 

4 

54- 57 

QTY01 

4 

ITEMS 

4 

58 

RTN01 

1 

ITEMS 

4 

59- 73 

PART02 

15 

ITEMS 

4 

74-103 

LESCR02 

30 

ITEMS 

4 

104-111 

SN02 

8 

ITEMS 

4 

112-115 

QfTY02 

4 
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ITEMS 

4 

116 

RTN02 

1 

ITEMS 

4 

117-131 

PARr03 

15 

ITEMS 

4 

132-161 

DESCR03 

30 

ITEMS 

4 

162-169 

SN03 

8 

ITEMS 

4 

170-173 

QTY03 

4 

ITEMS 

4 

174 

RTN03 

1 

ITEMS 

4 

175-189 

PART04 

15 

ITEMS 

4 

190-219 

LESCR04 

30 

ITEMS 

4 

220-227 

SN04 

8 

ITEMS 

4 

228-231 

QrY04 

4 

ITEMS 

4 

232 

RTN04 

1 

ITEMS 

4 

233 

MC«E 

1 
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OUTPUT STREAM DESCRIPTOR STREAM; AEMN377 


SUBSTREAM 

SUBSTREAM 

COLUMN 

FIELD 

FIELD 

NAME 

NU^BER 

BOUNDARIES 

NAME 

LENGTH 

HEADER 

1 

1- 6 

ATSNIJM 

6 

NAMAER 

2 

1- 30 

NAME 

30 

NAMAER 

2 

31- 60 

AIXR01 

30 

NAMAER 

2 

61- 90 

ADER02 

30 

NAMAER 

2 

91-120 

ADDR03 

30 

NAMAER 

2 

121-150 

ATIN 

30 

GENERAL 

3 

1 

SHIPVIA 

1 

^iENERAL 

3 

2 

SHIPHOW 

1 

GENERAL 

3 

3 

REPL 

1 

GENERAL 

3 

4 

INTC 

1 

GENERAL 

3 

5 

BILL 

1 

GENERAL 

3 

6- 13 

SONUM 

8 

GENERAL 

3 

14- 21 

CHGN 

8 

UENERAL 

3 

22- 29 

CPO 

8 

GENERAL 

3 

30- 59 

ACCOTHER 

30 

l^NERAL 

3 

60 

AIRSPARE 

1 

GENERAL 

3 

61- 69 

INS 

9 

ITEMS 

4 

1- 15 

PART01 

15 

ITEMS 

4 

16- 45 

DESCR01 

30 

ITEMS 

4 

46- 53 

ai0i 

8 

ITEMS 

4 

54- 57 

QTY01 

4 

ITEMS 

4 

58 

R'IN01 

1 

ITEMS 

4 

59- 73 

PART02 

15 

ITEMS 

4 

74-103 

1JESCR02 

30 

ITEMS 

4 

104-111 

SN02 

8 

ITEMS 

4 

112-115 

QrY02 

4 

ITEMS 

4 

116 

RTN02 

1 

ITEMS 

4 

117-131 

PART03 

15 

ITEMS 

4 

132-161 

DESCR03 

30 

ITEMS 

4 

162-169 

SN03 

8 

ITEMS 

4 

170-173 

QTY03 

4 

ITEMS 

4 

174 

R'IN03 

1 

ITEMS 

4 

175-189 

PART04 

15 

ITEMS 

4 

190-219 

DESCR04 

30 

ITEMS 

4 

220-227 

SN04 

8 

ITEMS 

4 

228-231 

QrY04 

4 

ITEMS 

4 

232 

RTN04 

1 

ITEMS 

4 

233 

M(»E 

1 

ERRCR 

5 

1- 40 

ERR 

40 
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(0073) 
(0074) 
(0075) 
(0076) 
(0077) 
(0078) 
(0079) 
(0080) 
(0081) 
(00 82) 
(0083) 
(0084) 
(0085) 
(0086) 
(0087) 
(0088) 
(0089) 
(0090) 
(0091) 
(0092) 
(0093) 
(0094) 
(0095) 
(0096) 
(0097) 
(0098) 
(0099) 
( 0100 ) 
( 0101 ) 
( 0102 ) 
(0103) 
(0104) 
(0105) 
(0106) 
(0107) 
(0108) 
(0109) 
( 0110 ) 
( 0111 ) 
( 0112 ) 
(0113) 
(0114) 
(0115) 
(0116) 
(0117) 
(0118) 
(0119) 
( 0120 ) 
( 0121 ) 
( 0122 ) 
(0123) 
(0124) 


PRIMEATS, FORMS XXX, 79/02/12 

* FRIMEATS, FORMS XXX, 79/02/12 

* PRIME AUTHORIZATION TO SHIP FORM — FORMS MMO 

* COPYRIGHT 1979 PRIME COMPUTER, FRAMINGHAM MA 

* 

* 

AEMN377 FORMAT 

EEVICE OWL1200 

* 

* -HEATER LINE INFORMATION: 

* 

FIELD 'FORM' POSITION (2,1) 

FORMNAME FIELD LENGTH 8, POSITION (7,1) 

FIELD 'ATS #' POSITION (20,1) 

ATSNUM FIELD LENGTH 6, POSITION (26,1) 

* 

* 

* -SHIP TO INFORMATION; 

* 

FIELD 'SHIP TO ' POSITION (2,3), REVERSE VIDEO 
FIELD 'NAME' POSITION (12,3) 

NAME FIELD LENGTH 30, POSITION (24,3), MDPROTECT 

FIELD 'ADIEESS' POSITION (12,4) 

REPEAT 3 

ADDR FIELD LENGTH 30, POSITION (24,+3), NOPROTBCT 

END REPEAT 

FIELD 'ATTENTION' POSITION (12,7) 

ATTO FIELD LENGTH 30 POBITIOL (24,7) NOPROTECT 

* 

* 

* -SHIP VIA INFORMATION; 

* 

FIELD 'SHIP VIA' POSITION (2,9), REVERSE VIDEO 
SHIPVIA FIELD LENGTH 1, POSITION (12,9) , NOPROTECT 

FIELD '**VIA COPES**' E>OSmON (62,1) 

FIELD '1. PICKUP' POSITION (62,2) 

FIELD '2. PARCEL POSITIC»JT' POSITION (62,3) 

FIELD '3. UPS' POSITION (62,4) 

FIELD '4. FIRST CLASS' POSITIOJ (62,5) 

FIELD '5. SPEC ISILIV POSITION (62,6) 

FIELD '6. TRUOK' POSITION (62,7) 

FIELD '7. FRI PARCEL' POSITION (62,8) 

FIELD '8. AIR FREIGHT' POSITION (62,9) 

FIELD '9. FEDR EXPR' POSITION (62,10) 

* 

* 

* -SHIP HOW INFORMATION: 

* 

FIELD 'SHIP HOW' POSITION (20,9), REVERSE VIDEO 
SHIPHCW FIELD LENGTH 1, POSITIOI (32,9) , NOEROTECT 

FIELD '**HOW CODES**' POSITION (62,12) 

FIELD '1. PREPAID', POSITION (62,13) 

FIELD '2. C.O.D.', POSITION (62,14) 
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(0125) 

(0126) 

(0127) 

(0128) 

(0129) 

(0130) 

(0131) 

(0132) 

(0133) 

(0134) 

(0135) 

(0136) 

(0137) 

(0138) 

(0139) 

(0140) 

(0141) 

(0142) 

(0143) 

(0144) 

(0145) 

(0146) 

(0147) 

(0148) 

(0149) 

(0150) 

(0151) 

(0152) 

(0153) 

(0154) 

(0155) 

(0156) 

(0157) 

(0158) 

(0159) 

(0160) 

(0161) 

(0162) 

(0163) 

(0164) 

(0165) 

(0166) 

(0167) 

(0168) 

(0169) 

(0170) 

(0171) 

(0172) 

(0173) 

(0174) 

(0175) 

(0176) 

(0177) 


FIELD '3. PREPAID/ADD', POSITION (62,15) 
FIELD '4. COLLECT', POSITION (62,16) 

* 

* 


* -ACCOUNTING INFCRMATIO^: 

* 

FIEtD 'ACCOUNT ' POSITION (2,11), REVERSE VIDEO 
FIELD 'REPLACE/SHCHT SHIP?' POSITION (12,11) 

REPL FIEtD LENGTH 1, POSITICW (33,11), NOPROTBCT 

FIELD 'S.O.', POSITIOJ (37,11) 

SONUM FIELD LENGTH 8, POSITION (50,11), NOPROTECT 

FIELD 'INTERISP^L CHARGE?' POSITION (12,12) 

INTC FIELD LENGTH 1, POSITION (33,12), NOPROTECT 

FIELD 'CHARGE It' POSITION (37,12) 

CHGN FIELD LENGTH 8, POSTTICW (50,12), NOFROTECT 

FIELD 'BILLABLE?', POSITION (12,13) 

BILL FIELD LENGTH 1, POSITION (33,13), NOPROTECT 

FIELD 'COST P.O. #', POSITION (37,13) 

CPO FIEtD LENGTH 8, POSITION (50,13), NOPROTECT 

FIELD 'OTHER:' POSITION (12,14) 

ACCOTHER FIEtD LENGTH 30, POSITION (20,14) NOPROTECT 

* 


* 


* - MISCELLANEOUS INFORMATION: 

* 

FIEtD 'MISC ' POSITION (2,16), REVERSE VIDEO 
FIELD 'INSURE FC» $' POSITIOJ (12,16) 

INS FIEtD LENGTH 9, POSITION (28,16),NOFROTECT 

FIELD 'AIR SPARE?' POSITIOJ (40,16) 

AIRSPACE FIEtD LENGTH 1, POSITION (52,16), NOFROTECT 

* 

* 


* -ITEM DESCRIPTION. 

* 

FIEtD 'PART NO' POSITION (5,18) 

FIELD 'ASCRIPTION' POSITION (29,18) 

FIEtD 'S/N' POSITION (53,18) 

FIEtD 'QTY' POSITION (61,18) 

FIEtD 'RTN' POSmOSI (66,18) 

REPEAT 4 

PART FIELD LENGTH 15, POSITION (2,+18), NOPROTECT 

ASCR FIELD LENGIH 30, POSITION (19,+18) , NOFROTECT 

SN FIELD LENGTH 8, POSITION (51,+18), NOPROTECT 

QTY FIELD LENGTH 4, POSITION (61,+18) , NOFROTECT 

RTN FIEtD LENGTH 1, POSITION (67,+18), NOPROTECT 

END REPEAT 

* 

FIEtD 'MAE?' POSITION (72,22) 

MCBE FIELD tENGTH 1, POSITION (79,22) , NOFROTECT 

* 

* 

* -ERROR MESSAGE, ETC. 

* 
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(0178) 

(0179) 

(0180) 

(0181) 

(0182) 

(0183) 

(0184) 

(0185) 

(0186) 

(0187) 

(0188) 

(0189) 

(0190) 

(0191) 

(0192) 

(0193) 

(0194) 

(0195) 

(0196) 

(0197) 

(0198) 

(0199) 

( 0200 ) 

( 0201 ) 

( 0202 ) 

(0203) 

(0204) 

(0205) 

(0206) 

(0207) 

(0208) 

(0209) 

( 0210 ) 

( 0211 ) 

( 0212 ) 

(0213) 

(0214) 

(0215) 

(0216) 

(0217) 

(0218) 

(0219) 

( 0220 ) 

( 0221 ) 

( 0222 ) 

(0223) 

(0224) 

(0225) 

(0226) 

(0227) 

(0228) 

(0229) 

(0230) 


ERR FIELD LENGTH 40, POSITIOJ (2,24) 

* 

* 

* 

END mVICE 
EEVICE VISTAR3 

* 

* -HEADER LINE INFGRMATIOI: 

* 

FIELD 'FORM’ POSITION (2,1) 

FOmNAME FIELD LENGTH 8, POSITION (7,1) 

FIELD 'ATS #' POSmON (20,1) 

ATSNUM FIELD LENGTH 6, POSITION (26,1) 

* 

* 


* -SHIP TO INFORMATION; 

* 

FIELD 'SHIP TO ' POSITION (2,3), REVERSE VIDEO 
FIELD 'NAME' POSITION (12,3) 

NAME FIELD LENGTH 30, POSITION (24,3), NOPROTECT 

FIELD 'ADDRESS' POSITION (12,4) 

REPEAT 3 

ADDR FIELD LENGTH 30, POSITION (24,+3), NOPROTECT 

END REPEAT 

FIELD 'ATTENTION' POSITION (12,7) 

ATTN FIELD LENGTH 30 POSITION (24,7) NOEROTECT 

* 

* 

* -SHIP VIA INFORMATION; 

* 


SHIPVIA 


* 


FIELD 'SHIP VIA' POSITIOI (2,9), REVERSE VIDEO 

FIELD LENGTH 1, POSITION (12,9) , NOFROTBCT 
FIELD '**VIA CODES**' POSITION (62,1) 

FIELD '1. PICKUP' POSITION (62,2) 

FIELD '2. PARCEL POSITIONT' POSITION (62,3) 

FIELD '3. UPS' POSITION (62,4) 

FIELD '4. FIRST CLASS' POSITION (62,5) 

FIELD '5. SPEC DELIV POSITION (62,6) 

FIELD '6. TRUCK' POSITION (62,7) 

FIELD '7. FRI PARCEL' POSITION (62,8) 

FIELD '8. AIR FREIGHT' POSITION (62,9) 

FIELD '9. FEDR EXFR' POSITION (62,10) 


* 


* -SHIP HOW INFORMATION; 

* 


FIELD 'SHIP HOW' POSITION (20,9), REVERSE VIDEO 
SHIIHOW FIELD LENGTH 1, POSITION (32,9) , NOFROTECT 

FIELD '**HOW CODES**' POSITION (62,12) 

FIELD '1. PREPAID', POSITION (62,13) 

FIELD '2. C.O.D.', POSITION (62,14) 

FIELD '3. E«EPAID/AIX)', POSITION (62,15) 

FIELD '4. COLLECT', POSITION (62,16) 


REV. 0 
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FORM ffiSCRIPTOR NO. 1 


(0231) 
(0232) 
(0233) 
(0234) 
(0235) 
(0236) 
(0237) 
(0238) 
(0239) 
(0240) 
(0241) 
(0242) 
(0243) 
(0244) 
(0245) 
(0246) 
(0247) 
(0248) 
(0249) 
(0250) 
(0251) 
(0252) 
(0253) 
(0254) 
(0255) 
(0256) 
(0257) 
(0258) 
(0259) 
(0260) 
(0261) 
(0262) 
(0263) 
(0264) 
(0265) 
(0266) 
(0267) 
(0268) 
(0269) 
(0270) 
(0271) 
(0272) 
(0273) 
(0274) 
(0275) 
(0276) 
(0277) 
(0278) 
(0279) 
(0 280) 
(0281) 
(0282) 
(0283) 


* 

* 


* -ACCOUNTING INFORMATION: 

* 

FIELD 'ACCOUNT ' POSITION (2,11), REVERSE VIDEO 
FIELD 'REPLACE/SHC»T SHIP?' POSITION (12,11) 

REPL FIELD LENGTH 1, POSITION (33,11), NOPROTECT 

FIELD 'S.O.', POSITION (37,11) 

SONUM FIELD LENGTH 8, POSITION (50,11), NDPROTBCT 

FIELD 'INTERNAL CHARGE?' POSITION (12,12) 

INTO FIELD LENGTH 1, POSITIOM (33,12), NOPROTECT 

FIELD 'CHARGE #' POSITION (37,12) 

CHGN FIELD LENGTH 8, POSITION (50,12), NOPROTECT 

FIELD 'BILLABLE?', POSITION (12,13) 

BILL FIELD LENGTH 1, POSITION (33,13), NOPROTBCT 

FIELD 'COST P.O. #', POSITION (37,13) 

CPO FIELD LENGTH 8, POSTTICN (50,13), NOPROTECT 

FIELD 'OTHER:' POSITION (12,14) 

ACCOTHER FIELD LENGTH 30, POSITION (20,14) NOPROTBCT 

* 

* 

* -MISCELLAfEOUS INFORMATIOI: 

* 

FIELD 'MISC ' POSITION (2,1,6), REVERSE VIDEO 
FIELD 'INSURE FOR $' POSITION (12,16) 

INS FIELD LENGTH 9, POSITION (28,16),NOFROTBCT 

FIELD 'AIR SPARE?' POSITION (40,16) 

AIRSPACE FIELD LENGTH 1, POSITION (52,16), NOPROTECT 

* 

* 


* -ITEM DESCRIPTICW. 

* 

FIELD 'PART NO' POSITION (5,18) 

FIELD 'INSCRIPTION' POSITION (29,18) 

FIELD 'S/N' POSITION (53,18) 

FIELD 'QTY' POSITION (61,18) 

FIELD 'RTN' POSITION (66,18) 

REPEAT 4 

PART FIELD LENGTH 15, POSITION (2,+18), NOPROTECT 

INSCR FIELD LENGTH 30, POSITION (19,+18) , NOFROTBCT 

SN FIELD LENGTH 8, POSITION (51,+18), NOPROTBCT 

QTY FIELD LENGTH 4, POSITION (61,+18) , NOPROTECT 

RTN FIELD LENGTH 1, POSITION (67,+18), NOPROTBCT 

END REPEAT 

* 

FIELD 'MCNE?' POSITION (72,22) 

MCNE FIELD LENGTH 1, POSITION (79,22), NOFROTECT 

* 

* 

* - ERROR MESSAGE, ETC. 

* 

ERR FIELD LENGTH 40, POSITIOl (2,24) 

* 
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(0284) * 

(0285) * 

(0286) END DEVICE 

(0287) END FOmAT 

0000 ERRORS (FDL, REV 15 - 16-FEB-78) 


REV. 0 
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FORM lESCRIPTOR NO 


1 


DEVICE FORMAT MAP FORMAT: AEMN377 DEVICE: OWL1200 SIZE: 24 BY 80 

0 

0 

_*_1_*_2_*_3_*_4....*_5_*_6_*_7_*....8 


0 1 
0 2 
0 3 
+ 

0 4 
+ 

0 5 
+ 

0 6 
+ 

0 7 
+ 

0 8 
0 9 
+ 

0 10 
0 11 
+ 

0 12 
+ 

0 13 
+ 

0 14 
+ 

0 15 
0 16 
+ 

0 17 
0 18 
0 19 
+ 

0 20 

0 21 
+ 

0 22 
+ 

0 23 
0 24 
0 


FORM ******** ATS # ****** **VIA CODES** 





1. 

PICKUP 

SHIP TO 

NAME 


2. 

PARCEL POSITIONT 


ADDRESS 


3. 

UPS 




4. 

FIRST CLASS 




5. 

SPEC DELIV 


ATTENTION 


6. 

TRUCK 




7. 

FRI PARCEL 

SHIP VIA 

SHIP HOW 


8. 

AIR FREIGHT 


- - 


9. 

FEER EXPR 

ACrOUNT 

REPLACE/SHORT SHIP? 

S.O. 




IMTERmL CHARGE? “ 

CHARGE # 

**HCW CODES** 


BILLABLE? “ 

COST P.O. # 

1. 

PREPAID 


OTHER: “ 


2. 

C.O.D. 




3. 

PREPAID/AIX) 

MISC 

INSURE FOR $ 

AIR SPARE? 

4. 

COLLECT 

PART NO UESCRIPTION S/N 

OTY 

RTN 


MORE? 


**************************************** 


PAGE: 1 


F 


11 


November 1979 








APPENDIX F 


PER3040 


DEVICE FORMAT MAP 


FORMAT: ADMN377 EEVICE: VISTAR3 


SIZE: 24 BY 80 


0 


.8 


FORM ******** ATS # ****** 
SHIP TO NAME 

ADDRESS 


ATTEOTION 


**VIA COEES** 

1. PICKUP 

2. PARCEL POSITIONT 

3. UPS 

4. FIRST CLASS 

5. SPEC DELIV 

6. TRUCK 


0 

8 

1 




7. 

PRI PARCEL 

0 

9 

1 

SHIP VIA 

SHIP HOW 


8. 

AIR FREIGHT 

+ 








0 

10 

1 




9. 

FEER EXPR 

0 

11 

I 

ACCOUNT 

REPLACE/SHCRT SHIP? 

S.O. 



+ 








0 

12 

1 


INTERNAL CHARGE? “ 

CHARGE # 

**H0W CODES** 

+ 








0 

13 

1 


BILLABLE? “ 

COST P.O. # 

1. 

PREPAID 

+ 








0 

14 

1 


OTHER: “* 


2. 

C.O.D. 

+ 








0 

15 

1 




3. 

PREPAID/ADD 

0 

16 

1 

MISC 

INSURE FOR $ 

AIR SPARE? 

4. 

COLLECT 

+ 








0 

17 

1 






0 

18 

1 

PART NO UESCRIPTION S/N 

gPY 

RTN 

0 

19 

1 






+ 








0 

20 

1 






+ 








0 

21 

1 






+ 








0 

22 

1 





~ MORE? 

+ 








0 

23 

1 






0 

24 

1 

**************************************** 
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Section 8. 


G 


1 


November 1979 



APPENDIX G 


Pm3040 


REV 15. J 
■( 0001 ) 
( 0002 ) 
(0003) 
(0004) 
(0005) 
(0006) 
(0007) 
(0008) 
(0009) 
( 0010 ) 
( 0011 ) 
( 0012 ) 
(0013) 
(0014) 
(0015) 
(0016) 
(0017) 
(0018) 
(0019) 
( 0020 ) 
( 0021 ) 
( 0022 ) 
(0023) 
(0024) 
(0025) 
(0026) 
(0027) 
(0028) 
(0029) 
(0030) 
(0031) 
(0032) 
(0033) 
(0034) 
(0035) 
(0036) 
(0037) 
(0038) 
(0039) 
(0040) 
(0041) 
(0042) 
(0043) 
(0044) 
(0045) 
(0046) 
(0047) 
(0043) 
(0049) 
(0050) 
(0051) 
(0052) 


COBOL SOURCE FILE: DEMOl 08/13/79 13:52 

IDENTIFICATION DIVISION. 
mOGRAM-ID. MAIN. 

REMARKS. A PROGRAM TO ACCEPT ORDERS FROl THE VDU 
AND WHITE OUT A MIEAS FILE. 

ENVIRONMENT DIVISION. 

INPUT-Oin’PUT SECTION. 

FILE-CCKTROL. 

SELECT INFILE ASSIGN TO TERMINAL. 

SELECT ORDER-FILE ASSI® TO PFMS 
ORGANIZATION IS INIEXED 
ACCESS IS DYNAMIC 
RECORD KEY IS ORDER-KEY 

ALTERNATE RECORD KEY IS ORDER-NAME WITH DUPLICATES 
ALTERNATE RECORD KEY IS STOCK-NO WITH DUPLICATES 
ALTERNATE RECORD KEY IS STOCK-DEL WITH DUPLICATES. 

LATA DIVISION. 

FILE SECTION. 

FD INFILE LABEL RECORDS ARE OMITTED. 

01 SCR. 

02 FILLER PIC X (104). 

FD ORDER-^ILE LABEL RECORDS ARE STANDARD 
VALUE OF FILE-ID IS "ORDERS”. 

01 ORDER-RECORD. 

02 ORDER-KEY. 


03 ORDERHMO PIC 9(5). 

03 ORDER-ITEM PIC 99. 


02 ORDER-WAME 

PIC 

X(20). 

02 CRDER-AE»1 

PIC 

X(20) . 

02 ORDER-ADD2 

PIC 

X(20) . 

02 ORDER-ADU3 

PIC 

X(20) . 

02 STOCK-NO 

PIC 

X(6). 

02 STOCK-UEL 

PIC 

X(8) . 

02 STOCK-QTY 
ORDERC. 

PIC 

S9(5) SIGN TRAILING SEPARATE 

02 FILLER 

PIC 

X(7). 

02 NEXl’-CRi:»R 

PIC 

9(5) . 

02 FILLER 

PIC 

X(94) . 


wokking-storage section. 

77 INV-C PIC X(12) VALUE *|f#INVDKE DSl* . 

77 REL-C PIC X(09) ^ALUE '##RELEASE* 

77 PROT-C PIC X(25) VALUE 'tffPROTBCT NAM ADI AD2 AD3* . 

77 ENAB-C PIC X(24) \ALUE *##ENABLE NAM ADI AD2 AD3* . 

77 CLEAR-C PIC X(07) VALUE *»CLEAR*. 

77 CLA-C PIC X (11) V^LUE * ##CLEAR ALL* . 

77 CURR-ORD PIC 9(5). 

01 DATA-SCREEN. 


02 

DS-NAM. 



03 CUSIND 

PIC XX. 


03 FILLER 

PIC X(18) 

02 

DB-ADl 

PIC X (20) . 

02 

DS-AD2 

PIC X(20). 

02 

DS-AU3 

PIC X (20) . 
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(0053) 


02 DB-STK. 

(0054) 


03 STK-ID PIC XX. 

(0055) 


03 FILLER PICX(4). 

(0056) 


02 DS-QTY PIC 9(5). 

(0057) 


02 DS-miE PIC X (8) . 

(0058) 


02 DS-ORIER PIC 9(5). 

(0059) 


PROCEDURE DIVISION. 

(0060) 


START-POINT. 

(0061) 


CALL 'FOR4$I'. 

(0062) 


OreN I-O ORffiR-^ILE. 

(0063) 


OPEN I-O INFILE. 

(0064) 


WRITE SCR FROM INV-C. 

(0065) 


B-POINT. 

(0066) 


READ INFILE INTO DATA-SCREEN. 

(0067) 


IF CUSIND EQUAL '**' GO TO END-IT. 

(0068) 

* 


(0069) 

•k 


(0070) 

TRY-IT. 

(0071) 


MOVE ZEROES TO ORDER-KEY. 

(0072) 


READ OREER-FILE KEY IS QRIER-KEY INVALID KEY 

(0073) 


GO TO TRY-IT. 

(0074) 


AK) 1 TO NEXT-ORIER. 

(0075) 


MOVE NEXT-CRIER TO CURR-CRD. 

(0076) 


REWRITE (SIIER-41ECCRD. 

(0077) 

k 


(0078) 

k 


(0079) 


MOVE DS-NAM TO ORIER-44AME. 

(0080) 


MOVE EB-ADl TO CRDER-ADDl. 

(0081) 


MOVE DB-AD2 TO OREER^DD2. 

(0082) 


MOVE E6-AD3 TO CRDER-ADD3. 

(0083) 


MOVE ZERO TO ORDER-ITEM. 

(0084) 

A-POINT. 

(0085) 


MOVE DG-STK TO STOCK-NO. 

(0086) 


lEBPBCT DB-STK REPLACING LEADING SPACES BY ZEROES. 

(0087) 


MOVE DB^Y TO STOCK-^Y. 

(0088) 


MOVE DB-DATE TO STOCK-IEL. 

(0089) 

* 


(0090) 

* 


(0091) 


ADD 1 TO ORDER-ITEM. 

(0092) 


MOVE CURR-CRD TO CRDER^IO. 

(0093) 


MOVE CURR-ORD TO DS-ORDER. 

(0094) 

k 


(0095) 

k 


(0096) 


WRITE ORDER-RECORD. 

(0097) 


WRITE SCR FRCM PROT-C. 

(0098) 


MOVE SPACES TO DB-STK, DB^Y, DB-DATE. 

(0099) 


WRITE SCR FRCM DATA-SCREEN. 

(0100) 


READ INFILE INTO DATA-SCREEN. 

(0101) 


IF SIK-ID NOT EQUAL '**' GO TO A-POINT. 

(0102) 

k 


(0103) 

k 


(0104) 


WRITE SCR FRCM ENAB-C. 

(0105) 


WRITE SCR FRCM CLEAR-C. 
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(0106) 

GO TO 

B-POINT. 

(0107) 

* 


(0108) 

* 


(0109) 

END-IT. 


(0110) 

CLOSE 

ORDER-FILE. 

(0111) 

WRITE 

SCR FROM CLA-C. 

(0112) 

WRITE 

SCR FROM REL-C. 

(0113) 

CLOSE 

INFILE. 

(0114) 

STOP ' 

'END OF ORDER ENTRY 


0071 Ai/ MOVE IS DONE WITHOUT CONVERSION. 


PROGRAM STATISTICS 


EXECUTABLE COM: SIZE: 453 WC»DS. 
CONSTANT POOL SIZE: 35 WORDS. 

TOTAL PURE PROCEDURE SIZE: 488 WORDS. 

WORKING-STC»AGE SIZE: 202 BYTES. 
TOTAL LINKFRAME SIZE: 499 WCBDS. 

STACK SIZE: 29 WORDS. 

TRACE MODE: OFF. 

NO ARGLMENTS EXPECTED. 

114 SOURCE LINES. 


NO ERRORS, 1 WARNINGS, P400/500 COBOL REV 15.3 


REV. 0 
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FORM DESCRIPTOR FC» 
COBOL PROGRAM EXAMPLE 


This appendix is a complete listing of the example 
associated with the program discussed in Section 8. 
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(0001) 

DSl 

STREAM 



(0002) 

NAM 

FIELD NAM 

LENGTH 

20 

(0003) 

ADI 

FIELD ADI 

LENGTH 

20 

(0004) 

AD2 

FIELD AD2 

LENGTH 

20 

(0005) 

AD3 

FIELD AD3 

LENGTH 

20 


(0005) STKNNO FIELD STKNO LENGTH 6 

(0007) STKQTY FIELD STKQTY LENGFH 5 JUSTIFY RIGHT 

(0008) STKffiL FIELD Sl’KISlL IFNGTH 8 

(0009) ONO FIELD ONO LENGTH 5 OUTPUT 

(0010) END STREAM 

0000 ERRORS (FDL, REV 16 - 16-FEB-79) 


REV. 
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FORM DESCRIPTOR NO. 2 


INPUT 

S T R E 

AM DESCRIPTOR STREM 

COLUMN 

FIE ID 

FIELD 

BOUNDARIES 

NME 

LENC3TH 

1- 20 

NAM 

20 

21- 40 

ADI 

20 

41- 60 

AD2 

20 

61- 80 

AD3 

20 

81- 86 

STKNO 

6 

87- 91 

STKgTY 

5 

92- 99 

STKDEL 

8 


DBl 


H 


3 


November 1979 



APPENDIX H 


Pm3040 


OUTPUT STREAM DESCRIPTOR STREAM; 
COLUMN FIELD FIELD 

BOUNDARIES NAME LENGTH 


1- 20 

NAM 

20 

21- 40 

ADI 

20 

41- 60 

AD2 

20 

61- 80 

AD3 

20 

81- 86 

STKNO 

6 

87- 91 

STKQTY 

5 

92- 99 

SrKDEL 

8 

100-104 

ONO 

5 


DSl 


REV. 
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FOm DESCRIPTOR NO. 2 


( 0011 ) 
( 0012 ) 
(0013) 
(0014) 
(0015) 
(0016) 
(0017) 
(0018) 
(0019) 
( 0020 ) 
( 0021 ) 
( 0022 ) 
(0023) 
(0024) 
(0025) 
(0026) 
(0027) 
(0028) 
(0029) 
(0030) 
(0031) 
(0032) 
(0033) 
(0034) 
(0035) 
(0036) 
(0037) 
(0038) 
(0039) 
(0040) 
(0041) 
(0042) 
(0043) 
(0044) 
(0045) 
(0046) 
(0047) 
(0048) 
(0049) 
(0050) 
(0051) 


*********** 

*********** 

*********** 

DSl FORMAT 

DEVICE VISTftR3 

FIELD 'ORDER ENTRY SYSTEM' POSITION (22,2) 

FIELD '- - -' POSITION (22,3) 

FIELD 'ACCCXNT NAME ' POSITICN (10,6) 

NAM FIELD LENGTH 20 POSITION (35,6) NOFROTECT 
FIELD ' AND AIS^ESS' POSITION (10,7) 

ADI FIELD LENGTH 20 POSITION (35,7) NOEROTECT 

AD2 FIELD LENGTH 20 POSITION (35,8) NOFROTECT 

AD3 FIELD LENGTH 20 POSITICN (35,9) NOlROTECT 

FIELD 'STOCK NUMBER' POSITION (10,12) 

STKNO FIELD LENGTH 6 POSITICN (35,12) NOFROTECT 

FIELD 'QUANTITY' POSITION (10,14) 

STKQTY FIELD LENGTH 5 POSITICN (35,14) NOFROTECT 
FIELD 'DELIVERY DATE' POSITION (10,16) 

STKIEL FIELD LENGTH 8 POSITION (35,16) NOFROTECT 
FIELD 'ORDER REFERENCE IS' POSITION (10,20) 

ONO FIELD LENGTH 5 POSITICN (35,20) 

END DEVICE 
DEVICE aWLl200 

FIELD 'ORDER ENTRY SYSTEM' POSITICN (22,2) 

FIELD '- - -' POSITION (22,3) 

FIELD 'ACCOUNT NAME ' POSITION (10,6) 

NAM FIELD LENGTH 20 POSITICN (35,6) NOFROTECT 

FIELD ' AND AINRESS' POSITION (10,7) 

ADI FIELD LENGTH 20 POSITION (35,7) NOEROTECT 

AD2 FIELD LENGIH 20 POSITICN (35,8) NOFROTECT 

AD3 FIELD LENGTH 20 POSITION (35,9) NOiROTECT 

FIELD 'STOCK NUMBER' POSmON (10,12) 

STKNO FIELD LENGTH 6 POSITICN (35,12) NOPROTECr 
FIELD 'QUANTITY' POSITICN (10,14) 

STKQTY FIELD LENGTH 5 PCEITICN (35,14) NOEROTECT 
FIELD 'DELIVERY DATE' POSITICN (10,16) 

STKDEL FIELD LENGTH 8 POSITION (35,16) NOFROTECT 
FIELD 'ORINR FCEFERENCE IS' POSITION (10,20) 

ONO FIELD LENGTH 5 POSITICN (35,20) 

END EEVLCE 
END FORMAT 
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DEVICE FORMAT MAP FORMAT: DSl DEVICE; VISTAR3 SIZE; 24 BY 80 PAGE; 1 

0 

0 

-*-1-*-2-*-3-*-4_*_5_*_6_*_7_*....8 


0 1 
0 2 
0 3 
0 4 
0 5 
0 6 
+ 

0 7 
+ 

0 8 
+ 

0 9 
+ 

0 10 
0 11 
0 12 
+ 

0 13 
0 14 
+ 

0 15 
0 16 
+ 

0 17 
0 18 
0 19 
0 20 
0 21 
0 22 
0 23 
0 24 
0 


ORDER ENTRY SYSTEM 

ACCOUNT NAME 
AND ADDRESS 

STOCK NUMBER 

QUANTITY 

DELIVERY DATE 


ORDER REFEREICE IS ***** 
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FOM reSCRIPTOR NO. 2 


DEVICE FORMAT MAP 

0 

0 


FORMAT: DBl DEVICE: CWL1200 SIZE: 24 BY 80 

.*....4....*....5....*....6....*....7....*....8 


0 1 
0 2 
0 3 
0 4 
0 5 
0 6 
+ 

0 7 
+ 

0 8 
+ 

0 9 
+ 

0 10 
0 11 
0 12 
+ 

0 13 
0 14 
+ 

0 15 
0 16 


0 17 
0 18 
0 19 
0 20 
0 21 
0 22 
0 23 
0 24 
0 



ORDER ENTRY SYSTEM 



ACCOUNT NAME 



AND ADDRESS 



STOCK NUMBER 



QUANTITY 



DELIVERY DATE 



OREER REFERENCE IS ***** 
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PAGE: 1 
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APPENDIX I 

ADVANCED USE OF FORMS 


This appendix gives an example of FORMS used in conjunction with an 
external login program. (Refer to the ^sterns Aiministrator's Qaide 
PER3109). This program should be installed locally under the 
supervision of the system administrator. It is a good example of how 
forms can be used to produce a menu-driven approach to operation, and 
it is also a good example of how to use COBOL to produce an external 
login program. 

The program is listed on the following pages. 
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IDENTIFICATION DIVISION. 

PROGRAM-ID. DEMO. 

* 

* THIS CCBOL PROGRAM WAS DEVELOPED WITH THE PRIME FORMS 

* PACP^AGE TO DEMONSTRATE THE ABILITY TO FORMAT SCREENS 

* WITH A 'MENU' APPROACH TO OKRATOR INTERACTION. 

* 

* THE SCREEN EGFINITIONS ARE CONTAINED IN THE FILES 

* lOGINOl FIRST MENU 

* L0GIN02 SECOND MENU 

* IDGIN03 PASSWORD VALUATION SCREEN 

* 

* THE ONLY 'TRICKY' CODE IN THE PROGRAM IS THE SPECIAL 

* PROGRAMMING NECESSARY TO ALLOW THIS CODE TO BE SAVED 

* AS AN R-MODE VERSION IN CMDNCO KNOWN BY THE NAME 

* 'LOGIN' 

* THE R-MCDE COMPILE OF THIS PROGRAM LBES THE STOP LITERAL. 

* THE V-MODE VERSION LBES THE 'EXIT IROGRAM' IN A DUMMY 

* PARAGRAPH TO FAKE THE COMPILER INTO THINKING THAT THIS 

* IS A COBOL SUBROUTINE - HENCE NO FILE ASSIGNMENTS - EVER. 

* 

* THE R-MODE SEQUENCE IS TO R * COB. FORM 

* ENTER A SLASH FOR FILE ASSIGNMENTS 

* AND SAVE THE RESULT WITH lA77777 

* THE V-MOEE VERSION MUST BE SEC'ED AND THEN HUN THROUGH 

* THE SEG UFD COMMAND PROCEDURE 'CO CMDSEG' THAT WILL MAKE IT 

* LOOK LIKE THE R-MODE COUNTERPART. THENCE OFF TO aMDNC0 AS 'LOGIN' . 

* 

* THE PRIME SYSTEM SUBROUTINE 'TIMIAT' CAN BE CALLED 

* FROM THIS PROGRAM MODULE TO IF^VE ACCESS TO LOGIN 

* SESSION RESOURCE CONSUMPTICW CATA. 

* THIS USER DEPENLENT lATA MIGHT BE WHITTEN OUT TO A 

* DISK JOB ACCOUNTING FILE FOR FURTHER PROCESSING. 

* 

* 


ENVIRONMENT DIVESICW. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT FORM ASSIGN TO TERMINAL. 

* 

* 

* 


DATA DIVISION. 
FILE SECTION. 

* 

* 


FD FORM LABEL RECORDS ARE OMITTED. 

01 FOPM-REC(»D PIC X (40) . 

* 

* 


WORKING-STORAGE SECTION. 

01 INVOKE-COMMAND. 

05 INVOKE-LITERAL PIC X(9) VALUE 'D#INVDKE'. 
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05 INVOKE-FOPM-NAME 

PIC X{8) 

VALUE 

SPACES. 

01 

RELEASE-COMMAND 

PIC X(9) 

VALUE 

'#|fREI£ASE' . 

01 

CLEAR-COMMAND 

PIC X(7) 

VALUE 

'D#CLEAR'. 

01 

CLEAR-ALL-COMMAND 

PIC X(ll) 

VALUE 

'##CLEAR ALL'. 

01 

FUNCTIOn-KEY-ENABI£ 

PIC X(10) 

VALUE 

'##FKEffi ON'. 

01 

FUNCTION^EY-RETURN 

PIC X(3) 

. 


01 

ABSOLUTE-POSITION 

PIC X(17) 

VALUE '##fOBITION SELECT' 

01 

PASSWORD-RESPONSE 

PIC X(8) VALUE 

: SPACES. 

01 

COMMAND-LINE. 





05 LOGOUT-COMMAND 

PIC X(6). 




05 ABBREVIATED-LO REDEblNES LOGOUT-CCMMAND. 
10 FILLER PIC X(2). 

10 SHORT-LOGOUT PIC X (2) . 

10 FILLER PIC X(2) . 

05 FILLER PIC X (30). 

* 

* 

* 


PROCEDURE DIVISION. 

PARAGRAFH-01. 

* STOP 'TEMPORARY HALT'. 

* THE STOP LITERAL IS USED FOR R-MOEE PGMS 

* TO ALLOW PROGRAM SAVING AFTER THE FILE ASSIQSIMENTS 

* 

* THE CMCREAD CALL IS USED TO ALLOW TOE USE OF THIS 

* PROGRAM AS A SYSTEM WIDE LOGIN ROUTINE 

* IT TRAPS THE LOGOUT COMMANDS TO INSIRE THAT THE USER 

* DOESN'T GET A MENU AT LOGOUT TIME I! 

* CALL 'CMREAD' USING COMMAND-LINE. 

* IF LOGOUT-CCMMAND EQUAL 'LOGOUT' OR 

* SHORT-LOGOUT EQUAL ' ' 

* STOP RUN 

* ELSE 

* NEXT SENTENOE. 

* 

* 

OPEN I-O FORM. 

* 

* PREPARE FIRST SCREEN MENU 

MOVE 'LOGIN01 ' TO INVOKE-FOm-NAME. 

WRITE FCFM^IECCRD FROM INVOKE-COMMAND. 

WRITE FORM-REOCRD FROM FUnCTIOn-KEY-ENABLE. 

WRITE FORM-RECORD FROM ABSOLUTE-POSITION. 

* 

* 

* 


PARAGRAPH-02. 

READ FORM INTO FUNCTION-KEY-RETURN. 
IF FUnCTIOn-KEY-RETURN EQUAL ' 06' 
GO TO PARAGRAFH-03 


ELSE 


* 


GO TO PARAGRAffl-99. 
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* 

* 


PARAC3RAPHH33 

WRITE FCRM-RECCRD FRCM CLEAR-ALL-CCMMAND. 
WRITE F0R1-RECCKD FROM RELEASE-CCMMAND. 

* PREPARE THE SECOND MENU SCREEN 
MOVE 'I£IGIN02' TO INVOKE-FOFM-nAME. 

WRITE FCRMHRECQRD FROM INVOKE-CCMMAND. 
WRITE FORM-RECCRD FROM FUNCTIOn-KEY-ENABLE. 
WRITE FORM^^ECCRD FROM ABSOLUTE-POSITION. 

* 


* 


* 


OK. .NCW GET THE FUNCTION KEY RETURN 
READ FORM INTO FUnCTIOn-KEYRETURN. 
IF FUNCTION^^EY-RETURN EQUAL ' 04' 

GO TD PARAGRAEH-04 

ELSE 


GO TO R\RAGRAPH-99. 


* 


* 


PARAGRAFH-04. 

WRITE FGRM-RECCRD FROM CLEAR-ALL-CQMMAND. 
WRITE FOPM-RBCCRD FROM RELEASE-CCMMAND. 
MOVE 'LOGIN03' TO INVOKE-FOFM-NAME. 

WRITE FOHM-RHJORD FRCM INVOKE-CCMMAND. 
READ FORM INTO PASSWORD-RESPONSE. 

IF PASSW0FIU-RESPO16E NOT EQUAL 'TB 
GO TO RARAGRAPH-99 

ELSE 


GO TO PARAGRAPH-98. 

* 


* 

* 

PARAGRAPH-98. 

* HOOK HERE FOR ACCOUNTING DATA 

* CR PASSWORD RECORDS ETC.. 

WRITE FORM-RECORD FROM CLEAR-ALL-COMMAND. 

WRITE FORM-RECORD FROM RELEASE-COMMAND. 

CLOSE FORM. 

DISPLAY ***** TRIAL BAIANCE APPLICATION INVOKED HERE ****'. 
STOP RUN. 

* 

* 


* 


PARAGRAPH-99. 

HOOK HERE FOR ACCOUNTING FILE INFO 
CALL 'TLMDAT' AND RECORD FUNCTION SEQUENCE AND PW 
WRITE FORM^ECORD FROM CLEAR-ALL-CQMMAND. 

WRITE FORM-RECORD FROM RELEASE-COMMAND. 

CLOSE FORM. 

DISPLAY 'FUNCTION ERROR TRAP INVOKED'. 

STOP RUN. 

PARAGRAPH-OUMMY. 
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Hie forms descriptor associated with this program is as follows: 

LOGIN01 STREAM 

FIELD SELECT LENGTH 1 
FIELD (DATE3,DATE3) 

FIELD (TIME1,TIME1) 

END STREAM 

* 

* 

* 

LOGIN01 FORMAT 

lEVICE C1WL1200 

FIELD ' I C P P350 CONTROL CENTER'; 

KBITION (15,2) NOEROTECT 
DATES FIELD LENGTH 8 POSITION (25,4) NOPROTECT 

TLMEl FIELD LENGTH 5 POBITICN (47,4) NOPROTBCT 

FIELD 'FI ACCOUNTS RECEimBLE' POSITIC»I (25,7) 

FIELD 'F2 ACCOUNTS JtAYABIF' KBITIC»1 (25,9) 

FIELD 'F3 WORD PROCESSING' POSITION (25,11) 

field 'F4 PROGRAM EEVELDFMENT' POSITION (25,13) 

FIELD 'F5 SYSTEM ADMINISTRATOR' POSmCN (25,15) 

FIELD 'F6 GENERAL LELX3ER' POSITION (25,17) 

FIELD 'SELECT FUNCTION KEY ACTIVITY' POSITION (5,21); 

NOtROTBCT BLINK 

SELECT FIELD LENGTH 1 POSITION (38,21) NOEROTECT 

END DEVICE 
END FORMAT 
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LOGIN02 STREAM 

FIELD SELECT LENGTH 1 
END STREAM 

* 


* 

* 


LOGIN02 FORMAT 

IKVICE OWL1200 

FIELD 'GENERAL LEDGER' POSITION (25,4); 
NOPROTBCT 

FIELD 'FI BUDGET RATIO ANALYSIS' POSITION (25,9) 

FIELD 'F2 JOURNAL' POSITICN (25,12) 

FIELD 'F3 PRCFrr LOSS STATEMENT' POSITION (25,15) 

FIELD 'F4 TRIAL BALANCE' POSITICN (25,18) 

FIELD 'SELECT FUNCTION KEY ACTIVITY' POSITION (5,21); 
NOi«OTECT BLINK 

SELECT FIELD LENGTH 1 POSITION (38,21) NOPROTBCT 
ENU DEVICE 
END FORMAT 


LOGIN 03 STREAM 

FIELD PASSWD LENGIH 8 
END STREAM 

* 

* 

LOGIN03 FORMAT 

DEVLCE aWL1200 

FIELD 'VALIDATE YOUR TRIAL BALANCE ACCESS PASSWORD' ; 
POSITION (10,12) 

PASSWD FIELD LENGTH 8 POSITION (58,12) NOPROTECT NODISK-AY 
END DEVICE 
END FORMAT 


I 


7 


Novanber 1979 




PDR3040 


ERROR MESSAGES 


APPENDIX J 
ERROR MESSAGES 


ERROR MESSAGE FORMAT 


All errors generated by the FDL translator and FAP are of the form; 

C#nn text message 

Where ^ represents a unique two-digit error code for each type of 
error. The message printed is a one-line diagnostic of the cause of 
the error and possibly vrfiat action has been taken by the translator. 
The following paragrajAis describe the error codes generated by FDL. 
Unless otherwise indicated, the statement that caused an error is 
ignored by FDL. 


FDL ERROR MESSAGES 

The following paragraphs list FDL error messages and explanations. 

C#00 BAD STATEMENT FORMAT 

The contents of the statement field is not an alphanumeric text 
item. 

C#01 STATEMENT NOT RECOGNIZED. 

The statemait field does not contain a valid FDL statement. 

C#02 ARGUMENT REQUIRED. 

An argument is required following the statement name. 

C#03 ARGUMENT TOO LONG. 

A text item exceeds 80 characters in length. 

C#04 MULTIPLY DEFINED MACRO. 

A macro by the same name already exists. This statement is 
ignored and the previous macro definition is retained. 

C#05 BAD NAME FIELD. 

The name field (starting in the left margin) contains an illegal 
character. 
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C#06 NAME REQUIRED. 

A name must be present in the name field (starting in the left 
margin). Ihis error is generally issued because a mapped field 
in the FCKMAT descriptor is missirg a name. 

C#07 STATEMENT FIELD IS BLANK. 

A name was present in the name field, but no statement follov\^d. 

C#08 NO END STATEMENT; END ASSUMED 

An end-of-file vas encountered while processing a STREAfM or 
FORMAT descriptor. An END STREAM or END FORMAT is assumed. 

C#09 NOT PROCESSING STREAM lESCRIPTOR. 

An END STREAM or SUBSTREAM statement was issued and a stream 
descriptor is not beirg processed. 

C#10 END SUBSTREAM MISSING. IT IS ASSUMED HERE. 

An END STREAM statement was issued while a substrean block was 
beirg processed. An END SuBSTREAM is assuned prior to the END 
STREAM. 

C#ll NOT PROCESSING SUBSTREAM 

An END SUBSTREAM statement was issued while not processing a 
substream block. 

C#12 NOT PROCESSING FORMAT 

An END FORMAT or a lEVICE statement was issued while not 
processing a FORMAT descriptor. 

C#13 END DEVICE MISSING. IT IS ASSUMED HERE. 

An END FORMAT was encountered while still processing a device 
description. An END DEVICE is generated prior to the END 
FORMAT. 

C#14 NOT PROCESSING DEVICE BLOCK. 

A FIELD definition was issued after a FORMAT statement, but 
before a DtiVICE block was started. 

C#15 END STATEMENT MISSING; IT IS ASSUMED HERE. 

A STREAM or FORMAT descriptor was not terminated before another 
was started. An END STREAM or END FORMAT is generated prior to 
this statement. 
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C#17 BAD PARAMETER. 

This indicates that an unrecognizable parameter was present on a 
flELD statanent. 

C#18 INVALID FORMAT NAME. 

The name supplied following the FORMAT parameter in the STREAM 
statement does not conform to the naming conventions discussed 
earlier in this docunent. 

C#19 NAME NOT PERMITTED. 

A name was present on a statement v\hich does not permit one. 
This usually means that a literal field in the FORMAT descriptor 
contains a name. 

C#21 ALREADY PRCTESSING SUBSTREAM. 

A SUBSTREAM statement ves issued viiile already processing a 
suDstream block. 

C#22 VALIDATION STRING MISSING. 

The VALIDATE parameter is present on a STREAM descriptor field, 
but is not followed by any validation masks. 

C#23 BAD JUSTIFY PARAMETER. 

The JUSTIFY parameter in the FIELD statement is not followed by 
one of its four valid arguments. 

C#24 MAPPING SPECIFICATION REQUIRED. 

A STREAM descriptor FIELD is not follov\ed by any mapping 
specification. 

C#25 BAD MAPPING SPECIFICATION. 

A STREAM descriptor FIELD is not follovred by a valid mapping 
specification. 

C#26 BAD LENGTH SPECIFICATION. 

The LENGTH parameter in either STREAI4 or FORMAT descriptor is 
not followed by a valid numeric argument. 

C#27 BAD INPUT-OUTPUT SPECIFICATION. 

An INEVT, OUTPUT, or INFUT-OUTPUT parameter has been misused. 
This usually means that INPUT-OUTPUT or OUTPUT has been issued 
vHien processing an input-literal field. 
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C#28 MAP FIELD NAME TOO LOIG. 

The map to field name in a STREAM descriptor FIELD is longer 
than eight characters. 

C#29 ALREADY TOOCESSING DEVICE BLOCK. 

A DEVICE Statement has been issued v^ile already processing a 
device block. 

C#30 SYNTAX ERROR. 

This general error message is issued whenever two items in a 
field definition are separated by an illegal character. 

C#31 BAD POSITICW PARMETER. 

The POSITION parameter in a FCSMAT descriptor FIELD is not 
followed by a valid argunent. 

C#32 POSITION OUT OF RANGE. 

One or more of the arguments in the POSITION parameter is zero. 
C#33 LENGTH PARMETER MISSING. 

The length declaration for a STREAM or FORMAT descriptor FIELD 
is required but not supplied. 

C#34 POSITION PARMEPER MISSING. 

The POSITION parameter in a FCPMAT descriptor FIELD is not 
supplied. 

C#35 UNRECOGNIZED SYSTEM INFORMATION FIELD NAME. 

The name specified in a System Information Field is 
unrecognized. 

C#36 INPUT/OUTPUT SPECIFICATION NOT PERMITTED. 

An INPUT, OUrPUT, or INPUT-OUTPUT specification was included on 
a system information field definition. 

C#37 UNRECOGNIZED PARMETER. 

See C#17. 
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C#38 NOT PRCEESSING STREAM/DEVICE FORMAT BLOCK. 

A field definition has been issued outside of a STREAM or FORMAT 
descriptor. This and all other FIELD declarations up to the 
next STREAM, FORMAT, or EEVICE statement are ignored. This 
error message is issued once per each violation. 

C#39 MULTIK.Y DEFINED SYMBOL. 

A FIELD name has been redefined within the same STREAM or FORMAT 
descriptor. This field is processed normally, but will produce 
undesired results at run-time. 

C#40 BAD START SPECIFICATION. 

The argunent following the START specification in the FIELD 
definition within a STREAM is not nuneric and greater than zero. 

C#41 ILLEGAL MACRO ARGUMENT SPECIFIER. 

The item tollowing the argument reference symbol (#) is not 
numeric and greater than zero. 

C#42 EOF ENCOUNTERED BEFORE END REPEAT. 

An end-of-file was encountered on the input file before a repeat 
block was terminated. This usually causes abortion of the 
translation. 

C#43 END REPEAT MISSING - REPEAT BLOCK IGNORED. 

An END statement was encountered v^ile processing a REPEAT 
block. The entire REPEAT block is ignored and the QJD statement 
processed. 

C#44 STATEMENT NOT ALLOWED WITHIN REPEAT BLOCK. 

A Statement other than a FIELD statement was found vdthin a 
REPEAT block. The statement is ignored; processing of the 
REPEAT block continues. 

C#45 INPUT/OUTPUT SPECIFICATION REQUIRED. 

An input/empty-condition or output-literal field did not contain 
a required INPITT or OUTPITT statement. 

C#46 INCONSISTENT SUBSTREAM USAGE. 

A FIELD definition appears outside of a SUBSTREAM block in a 
multi-record stream definition -or- the user has attempted to 
start a SUBSTREAM definition v*ien previously defined FIELDS do 
not reside within a SuBSTREAM. This error message is only 
issued once per STREAM descriptor. 
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FAP ERROR MESSAGES 

Like FDL error messages, all FAP error messages are of the form: 
t^nn text message 

The _t in the error code represents the error type. At present, there 
are three types: 

• F - file system/input file/control block error 

• S - syntax error 

• T - TCB or DCF format error 

nn represents a two-digit error nunnber, unique for each error message 
generated by FAP. 

The following par^rafiis list FAP error messages and explanations. 


F#00 CONTROL BLOCK UFD DOES NOT EXIST. 

An operation other than CREATE was attempted and the forms UFD 
('FORMS*') does not exist on the system. 

F#01 CONTROL BLOCK DIRECTORY DOES NOT EXIST. 

An operation other than CREATE was attempted and the FORMS 
segment directory ('FMS.**') does not exist within the FORMS 
UFD. 

F#04 INPUT FILE IS EMPTY. 

The input file specified in an ADD or REPLACE command is 
empty. 

F#05 PREMATURE EOF. 

An EOF was encountered on the input file in an ADD or REPLACE 
ccxnmand before the end-of-data record. The module is deleted 
from the control directory. This is usually caused by the 
user pressing the BREAK key in the middle of an FDL 
compilation. 

F#06 FILE DOES NOT EXIST. 

The input file specified in an AEO or REPLACE command does not 
exist in the current UFD. 

F#07 BAD INPUT FILE. 

The input file specified in an AEO or REPLACE conunand is not a 
valid FDL output binary file. No action is taken with this 
file. 
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F#08 I/O LIST OVERFLOW, LINK SUPPRESSED. 

FAP ran out of room v^ile attempting tx) link a STREAl'l 
definition to a FORMAT an out of roan vAiile attempting to link 
a STREAM definition to a FOMAT definition. The internal I/O 
buffer must be enlarged betore this form definition may be 
added. Increase the value of lOLSIZ in the $INSERT file 
FORMS>FAP>IOBUF$ and rebuild FAP. 

F#09 STREAM/FORMAT BUFFER OVERFLOW. 

FAP ran out of room attempting to read a STREAM or FORMAT 
descriptor binary ran out of roan attempting to read a STREAM 
or FORMAT descriptor binary file. The buffer must be enlarged 
and FAP rebuilt betore this form definition can be added. 
Increase the value of SFBSIZ in the $INSERT file 
FORMS>FAP>ICBUF$ and rebuild FAP. >FAP>ICBUF$ and rebuild 
FAP. 

F#10 ERROR READING STREAM / FORMAT DESCRIPTlOJ. 

A file system error occurred viiiile attempting to load a STREAM 
or FORMAT descriptor. 

F#ll ERROR READING / EELETING LINK FILE. 

A file system error occurred vihen FAP was trying to purge a 
linked form definition file. 

F#12 ERROR RENAMING LINK FILE. 

An error occurred vhen FAP attempted to rename a link file 
following a PURGE operation. 

S#00 FILE NAME REQUIRED. 

An AEO or REPLACE command was issued, but no file name 
followed. The command is ignored. 

S#01 BAD FORM NAME SPECIFIER. 

The form name specifier contained a syntax error. This 
conmand is ignored. 

S#02 BAD ARGUMENT. 

One of the parameters in the command line was not recognized. 
The command is ignored. 

S#03 BAD TYPE. 

The fom name specifier contained a type declaration other 
than STR (stream) or FMT (fomat). This command is ignored. 
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S#05 


S#06 


S#07 


T#00 


T#01 


T#02 


T#03 


T#04 


NO FORM NAME SPECIFIED. 

A PURGE command was issued without a required form name 
specifier. The PURGE cotimand is ignored. 

MISSING ARGUMENT. 

Ihe TCB command was issued without any following user number. 
The ccmmand is ignored. 

BAD USER NIMBER. 

The user number specified in the TCB command is not an integer 
nunber greater than zero. Ihe TCB catmand is ignored. 

BAD TERMINAL NAME. 

The user attempted to assign the name PRINTER as a terminal 
type in a TCB command. This is not permitted and the TCB 
command is ignored. 

DCF EEViCE INTERLUDE FIELD ERROR. 

The device interlude number field in the given DCF entry is 
not nuneric or greater than zero. The DCF must be edited and 
corrected before continuing. 

DCF EEVICE NAME FIELD ERROR. 

The device name field in the given DCF entry contains an 
illegal character or is empty. The DCF must be edited and 
corrected before continuing 

DCF DEVICE ABBREVIATION FIELD ERROR. 

The device abbreviation field in the given DCF entry is empty 
or contains a space or illegal character. The DCF must be 
edited and corrected before continuing. 

TCB LINE/COLIMN FIELD ERROR. 

The line or column specification field in the given DCF entry 
is empty, contains a non-numeric value, or is less than 1. 
The DCF must be edited and corrected before continuing. 

MAX DEVICE NUMBER EXCEEDED IN DCF. 

The DCF contains an entry with a device interlude number 
greater than fifty (50). This error is issued tram the 
GENERATE command only. Only fifty (50) (!) devices may be in 
use at one time. 
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T#05 DEVICE CONTROL FILE EMPTY. 

The DCF is empty and the user issued a TCB or GENERATE 
command. 

T#06 TERMINAL UNDEFINED. 

The terminal type specified in the TCB command is not present 
in DCF. 


J 


9 


November 1979 




INDEX 


##, prefix for run-time 
directives 3-1 

$INSERT files 5-19 

AI® command 6-1 

Advanced use of FORMS I-l 

Alternate input file 5-19 

implication progran, compiling 
7-18, 8-13 

Application program, loading 
7-18, 8-14 

implications programs, FORMS, how 
to write 2-1 

Attribute modification directives 
4-8 

BLINK parameter 5-15 
Bug chart D-1 

CLEAR, run-time directive 4-3 

COBOL program example, form 
descriptor for H-1 

COBOL program listing, sample 
G-1 

Compiling the application program 
7-18, 8-13 

Configurable I/O list 4-10 

Configuration file, terminal 
B-2 

Control file, device B-2 

CREATE command 6-2 

Creating the form descriptor file 
7-11, 8-9 

Data areas, setting up 7-13, 
8-10 


Data description, purpose of 
3-1 

Data format 3-2 

Data stream descriptor 3-2 

Default options 5-21 

DEFINE statement 5-17 

Defining device types 7-12, 

8-10 

Descriptor structure 5-2 

Descriptor, data stream 3-2 

Descriptor, device format 3-3 

Descriptor, field 3-2 

Device control file B-2 

Device definition database B-2 

Device definition statements 
5-5 

Device driver, offline printer 
B-4 

Device driver, CWl B-5 

Device driver, VISTAR/3 B-4 

Device drivers, installing C-6 

Device drivers. Prime supplied 
B-3 

Device drivers, user written 
C-1 

Device format descriptor 3-3 
Device I/O B-1 
Device I/O mechanism B-1 
Device input/output s^^tem B-1 


X - 1 



INIEX 


Device mapping scheme B-3 

DEVICE statement 5-5 

Device types, defining 7-12, 

8-10 

Direct field 5-6 

Directives, attribute 
modification 4-8 

Directory information A-1 

Display atrtribute Parameters 
5-15 

DISPLAY paraneter 5-16 

EJECT statement 5-19 

END DEVICE statonent 5-5 

END FORMAT statement 5-5 

END REPEAT Statement 5-18 

END STREAM Statement 5-4 

END SIBSTREAM statement 5-4 

Error handling, run-time 4-9 

Error messages J-1 

Example COBOL program 8-1 

Example FORTRAN program 7-1 

FAP canmand format 6-1 

FAP example 6-9 

FAP functions 1-6 

FAP overview 1-6 

FAP see also Forms Adninistrative 
Processor 

FAP, see FORMS Administrative 
Processor 


FDL 5-1 

FDL command 3-7 

FDL listing 3-9 

FDL listing details, specifying 
7-16, 8-12 

FDL options 3-9 

FDL source, translating 7-18, 
8-13 

FDL syntax 5-1 

FESL temporary files 5^-22 

FEt. translation command format 
5-20 

Field definition 3-4 

FIELD definition 3-4 

Field definition examples 
5-13, 5-16 

Field descriptor 3-2 

Field generation, iterative 
5-17 

FIELD parameter for FORMAT 
5-14 

FIELD parameters 5-8 

Field statement differences 
between FIELD and STREAM 
descriptors 3-7 

Field statements within a format 
descriptor 5-14 

Field statements within a stream 
descriptor 5-6 

FIELD types 5-6, 5-14 

File Description Language command 
3-7 


X 


2 


INDEX 


File handling, run-time 4-8 

Filler field 5-7 

FIX parameter 5-11 

FKEY5, run-time directive 4-1 

FORCEREAD, run-time directive 
4-4 

Form definition delimiter 
statements 5^2 

Form definition overview 2-1 

Form definition sunmary 3-3 

Form definitions 3-1 

Form description, setting up 
7-11, 8-9 

Form descriptor file, creating 
7-11, 8-9 

Form descriptor for CCBOL program 
example H-1 

Form descriptor for FCX^TRAN 
program example F-1 

Form descriptor preparation 
3-5 

Form, how to define 3-1 

Format coding 3-5 

FORMAT descriptor 3-2 

Format descriptor boundaries 
3-5 

Format of data 3-2 

FORMAT statement 5-5 

Forms Administrative Processor 
see also FAP 


FORMS Administrative Processor, 
see FAP 

FORMS Administrative Processor 
6-1 

Forms Catalog, installing form 
descriptor 7-18, 8-14 

FCW'IS Definition Catalog overview 
1-6 

Forms Definition Language 5-1 

FORMS directives sunmary 2-5 

FCTIMS directives, definitions 
2-3 

FORMS run-time directives 4-1 

FORMS, advantages of 1-2 

FORMS, components of 2-3 

FCPMS, purpose of 1-2 

FOERMS, using overview 2-3 

FORTRAN program example form 
descriptor F-1 

FORTRAN program, sample E-1 

FREE parameter 5-16 

Functional overview, FORMS and 
PRIMOS 1-4 

GENERATE command 6-3 

HOLD parameter 5-16 

I/O statement, FOERMS, how to 
write 2-1 

I/O, list, configurable 4-10 

Input data 7-14, 8-12 

Input empty conditional field 
5-7 


X - 3 



INDEX 


Input literal field 5-6 

INPUT paraneter 5-9 

INPUT-OUTPUT parameter 5-9 

Installing FORMS A-1 

INVOKE, run-time directive 4-5 

IOCS interlude B-1 

Iterative field generation 
5-17 

JOURNAL command 6-4 

JUSTIFY parameter 5-8, 5-15 

Language manuals, related 1-7 

Languages, application, for FORMS 
1-5 

LENGTH parameter 5-8, 5-15 

LINK command 6-4 

LIST command 6-5 

Listing control statements 
5-19 

Listing details, FDL, specifying 
7-16, 8-12 

Listing features 7-17 

Literal data 7-14, 8-12 

Literal field 5-14 

Loading the shared library 
4-10 

Macro definition 5-17 

Macro definitions, using 7-15 
Manual, using 1-1 


Manuals, related 1-7 

Mapped field 5-14 

Mapping scheme, device B-3 

Mapping stream and format 
descriptor fields 3-4 

MIDAS file template 8-15 

Naming conventions 5-2 

NOBLINK parameter 5-16 

NODISPLAY parameter 5-16 

NOFIX parameter 5-11 

NOLIST statement 5-19 

NOPROTECT attribute, using 3-5 

NOE^IOTECT parameter 5-15 

NORMAL VIDEO paraneter 5-16 

Offline printer device driver 
B-4 

Operating systan and utilities 
manuals, related 1-7 

Output data 7-14, 8-12 

Output literal field 5-6 

OUTPUT parameter 5-9 

Overview of FORMS 1-1 

Overview, manual 1-1 

Owl device driver B-5 

POSITION parameter 5-15 

Position parameter, relative 
5-18 

POSITION, run-time directive 
4-5 


X - 4 



INDEX 


FRIMOS interfaces 1-3 

PRINT, run-time directive 4-5 

Problem solving chart D-1 

Program, running 7-19, 8-16 

Progranming aids 5-16 

FROTBCT parameter 5-15 

PURGE command 6-5 

QUIT command 6-7 

Related manuals 1-7 

Relative position parameter 
5-18 

RELEASE, run-time directive 
4-6 

REPEAT statement 5-18 

Repeated text 7-16 

REPLACE conmand 6-7 

REVERSE VIDEO parameter 5-16 

Run-time directives, FORMS 4-1 

Run-time directives, using 4-1 

Run-time error handling 4-9 

Run-time file handling 4-8 

Run-time message 5-22 

Running the program 7-19, 8-16 

Sample COBOL program listing 
G-1 

Sample FCKTRAN program E-1 

Setting up a form description 
7-11, 8-9 


Shared library, loading 4-10 

SPACE-FILL parameter 5-9 

START parameter 5-12 

Stream coding 3-7 

STREAM definition statements 
5-4 

STREAM descriptor 3-2 

STREAM statement 5-4 

SUBSTREAM statanent 5-4 

SLBSTREAM, run-time directive 
4-6 

SUBSTREAMS, using 7-12 

Syntax, nx. S-1 

System informational field 5-7 

TCB command 6-7 

Template, MIDAS file 8-15 

Temporary files, FIX 5-22 

Terminal configuration file 
B-2 

Ttext, repeated 7-16 

Translating FIX source 7-18, 
8-13 

Trouble shooting D-1 

Using the manual 1-1 

VALIDATE parameter 5-10 

VALIDATE, run-time directive 
4-6 

Variable data 7-14, 8-12 


X - 5 



INDEX 


VISTAR/3 device driver B-4 
ZERO-FILL parameter 5-9 


X 


6 











